Kinvey JavaScript SDK

Common errors

• error: "The Authorization header in your request is malformed. An Authorization header should contain two parts separated by a space: a type (Basic or Kinvey) and a base64-encoded auth string.

  cause Incorrectly formatted Authorization header in HTTP requests, often due to a missing space after 'Basic' or 'Kinvey' in the header string.
  fix Ensure the Authorization header string adheres strictly to the `Type Base64String` format, including the space, for example, `Authorization: Basic <base64-encoded-credentials>`.

• Kinvey.init is not a function or is undefined

  cause The Kinvey SDK was not properly initialized or imported. This often happens if `Kinvey` is imported incorrectly (e.g., default import instead of namespace import) or if `Kinvey.init()` is called before the SDK is fully loaded.
  fix Ensure `import * as Kinvey from 'kinvey-js-sdk';` is used for the main entry point and that `Kinvey.init()` is called only after the SDK module has been fully evaluated. Check for typos in method names.

Warnings

• breaking The Kinvey platform has been officially sunsetted and is no longer actively supported or maintained by Progress Software. All users are advised to migrate to an alternative backend solution. This SDK will not receive further updates or security patches.
  Fix: Migrate your application's backend services to an alternative platform (e.g., AWS Amplify, Firebase, Back4App).
• deprecated Many Kinvey-related GitHub repositories, including those for specific SDK shims (e.g., HTML5, NativeScript, Node.js), have been archived and are now read-only, indicating that these components are no longer in active development.
  Fix: Avoid starting new projects with Kinvey SDKs. For existing projects, plan for migration away from the Kinvey ecosystem.
• gotcha Older versions of various Kinvey SDKs frequently used CommonJS `require()` syntax. While `kinvey-js-sdk` v8.0.0 provides TypeScript declarations, modern bundlers and Node.js environments may prefer or enforce ESM `import` statements.
  Fix: For new development or migration, always use ESM `import` syntax. If targeting older Node.js or non-transpiled environments, ensure your build process correctly handles CommonJS or dual packages.

Install

• npm install kinvey-js-sdk npm
• yarn add kinvey-js-sdk yarn
• pnpm add kinvey-js-sdk pnpm

Imports

• Kinvey
  wrong:

  const Kinvey = require('kinvey-js-sdk');

  correct:

  import * as Kinvey from 'kinvey-js-sdk';

  While CommonJS `require` might work in some older environments, the SDK ships with TypeScript declarations, implying a modern ESM setup is preferred. `Kinvey` is typically imported as a namespace.
• DataStore
  wrong:

  import DataStore from 'kinvey-js-sdk/DataStore';

  correct:

  import { DataStore } from 'kinvey-js-sdk';

  Named imports are used for accessing core services like `DataStore`. Direct path imports for sub-modules are generally incorrect.
• User

  import { User } from 'kinvey-js-sdk';

  The `User` service for authentication and user management is a commonly imported named export.

Quickstart

This quickstart demonstrates how to initialize the Kinvey SDK, log in (or sign up) a user, save data to a collection, and retrieve data using a query. It highlights core functionalities of the backend-as-a-service platform.

import * as Kinvey from 'kinvey-js-sdk';

const APP_KEY = process.env.KINVEY_APP_KEY ?? '';
const APP_SECRET = process.env.KINVEY_APP_SECRET ?? '';

async function initializeAndLogin() {
  try {
    if (!APP_KEY || !APP_SECRET) {
      throw new Error('Kinvey App Key and App Secret must be provided via environment variables.');
    }

    // 1. Initialize Kinvey SDK
    await Kinvey.init({
      appKey: APP_KEY,
      appSecret: APP_SECRET,
      // Optional: Set masterSecret if using a Node.js environment
      // masterSecret: process.env.KINVEY_MASTER_SECRET
    });
    console.log('Kinvey SDK initialized successfully.');

    // 2. Login a user (or signup)
    let user;
    try {
      user = await Kinvey.User.login('testuser', 'password123');
      console.log(`User 'testuser' logged in:`, user.data);
    } catch (error) {
      if (error.statusCode === 401) { // User not found, attempt signup
        user = await Kinvey.User.signup('testuser', 'password123');
        console.log(`User 'testuser' signed up and logged in:`, user.data);
      } else {
        throw error;
      }
    }

    // 3. Access a data collection
    const collection = Kinvey.DataStore.collection('myCollection');

    // 4. Create and save a new entity
    const entity = await collection.save({ message: 'Hello Kinvey!', timestamp: new Date() });
    console.log('Saved entity:', entity);

    // 5. Fetch entities
    const query = new Kinvey.Query();
    query.greaterThan('timestamp', new Date(Date.now() - 24 * 60 * 60 * 1000)); // Last 24 hours
    const entities = await collection.find(query).toPromise();
    console.log('Fetched entities:', entities);

  } catch (error) {
    console.error('Kinvey operation failed:', error.message || error);
  }
}

initializeAndLogin();