Kimmio SDK

TypeScript SDK for using Kimmio app tokens, case creation, credentials, and workflow runtime APIs outside the Kimmio platform.

Use it from Node.js, Bun, Deno, or browser-based Kimmio apps when you need to:

• create project cases from an app
• attach one or more files to a created case
• read credential metadata or active credential values
• start workflow activation executions

Install

npm install @kimmio/sdk

Quick Start

import { Kimmio } from "@kimmio/sdk";

const client = new Kimmio({
  url: "https://app.kimmio.com",
  token: process.env.KIMMIO_TOKEN,
});

url defaults to https://app.kimmio.com. KimmioClient, baseUrl, and apiKey remain available as compatibility aliases.

Create a Case

Use an app token for app gateway calls. App tokens start with kimapp_ and are sent with the x-kimmio-app-token header.

import { Kimmio } from "@kimmio/sdk";

const client = new Kimmio({
  token: process.env.KIMMIO_APP_TOKEN,
});

const createdCase = await client.cases.create("refund_request", {
  orderId: "ord_123",
  amount: 120,
}, {
  projectId: "project-id",
});

Create a Case with Files

Files can be passed in parameters.file, parameters.files, parameters.attachment, parameters.attachments, or options.files.

const createdCase = await client.cases.create("refund_request", {
  orderId: "ord_123",
  amount: 120,
  files: [
    {
      name: "receipt.txt",
      type: "text/plain",
      content: "Receipt total: 120",
      attachmentType: "evidence",
    },
  ],
}, {
  projectId: "project-id",
});

Use fileId to attach an existing project file:

await client.cases.create("refund_request", {
  orderId: "ord_123",
}, {
  projectId: "project-id",
  files: [
    {
      fileId: "existing-project-file-id",
      attachmentType: "reference",
    },
  ],
});

Use contentBase64, Uint8Array, ArrayBuffer, Blob, or browser File for binary content:

await client.cases.create("kyc_review", {
  customerId: "cus_123",
}, {
  projectId: "project-id",
  files: [
    {
      name: "document.pdf",
      type: "application/pdf",
      contentBase64: pdfBase64,
      attachmentType: "evidence",
    },
  ],
});

Inline file payloads are intended for small files. For large files, upload or create the project file first and pass fileId.

Credentials

Read credential metadata by ID:

const credential = await client.credentials.get("credential-id", {
  query: {
    projectId: "project-id",
  },
});

Resolve by label and read the active credential value:

const credentialValue = await client.credentials.getValue("billing-stripe", {
  by: "label",
  query: {
    projectId: "project-id",
    environment: "editor",
  },
});

client.credentials.get(ref) resolves ref as a credential ID by default and returns metadata only. Use by: "label" to resolve by credential label.

client.credentials.getValue(ref) returns decrypted credential values from the active version. The returned object includes value and form for the saved credential payload, plus store for provider/runtime store data. Label lookup requires visibleFromScope or scoped query values such as projectId and environment.

Workflows

const run = await client.workflows.runActivation({
  activationId: "activation-id",
  eventType: "manual",
  payload: {
    customerId: "cus_123",
  },
});

Authentication

The SDK sends API keys with the x-api-key header. Tokens that start with kimapp_ are treated as app tokens and sent with x-kimmio-app-token for app gateway calls such as case creation. Create a Kimmio API key or app token with permissions that match the operation you are calling. Reading workflow credentials requires worker credential read permissions on the platform.

Examples

The example/ folder contains TypeScript examples runnable with Bun:

cd SDK
npm run build
KIMMIO_TOKEN=... KIMMIO_CREDENTIAL_REF=... npm run example:credentials
KIMMIO_TOKEN=... KIMMIO_CREDENTIAL_REF=... KIMMIO_CREDENTIAL_BY=label KIMMIO_PROJECT_ID=... KIMMIO_ENVIRONMENT=editor npm run example:credentials
KIMMIO_TOKEN=... KIMMIO_CREDENTIAL_REF=... KIMMIO_INCLUDE_VALUE=true npm run example:credentials
KIMMIO_TOKEN=... KIMMIO_ACTIVATION_ID=... KIMMIO_EVENT_TYPE=manual npm run example:workflow

AI Agent Docs

For AI agents and code-generation tools:

• Start with llms.txt for a compact index.
• Use llms-full.txt for the complete SDK guide in one plain-text file.
• Use docs/sdk.md for human-readable API reference.

The npm package includes these files, so agents can read them after installing the package without needing a website.

Publishing

Before publishing, make sure the npm kimmio organization exists and that the publishing account has access to @kimmio/sdk.

cd SDK
npm ci
npm run verify
npm run publish:preflight
npm run publish:npm

If npm requires a one-time password, pass it through npm config:

NPM_CONFIG_OTP=123456 npm run publish:npm

If publishing fails with E404 Not Found - PUT https://registry.npmjs.org/@kimmio%2fsdk, npm is rejecting the @kimmio scope. Fix one of these before retrying:

• Create the npm organization named kimmio.
• Or log in as the npm user named kimmio.
• Or add the current npm user/token to the kimmio organization with package publish permissions.
• Or rename the package to a scope you control.

For provenance from a local machine:

npm run publish:npm:provenance

For CI publishing, add an NPM_TOKEN repository secret and push a tag such as:

git tag sdk-v0.1.0
git push origin sdk-v0.1.0

The package builds to dist/ and publishes only dist/, docs/, examples, llms.txt, llms-full.txt, CHANGELOG.md, LICENSE.md, README.md, and package.json.