Runtime API

@tailor-platform/sdk/runtime provides typed wrappers for the tailor.* and tailordb.file APIs that the Tailor Platform Function runtime injects into the global scope at execution time. The wrappers are thin and delegate to the platform-provided globals; they exist so that you can:

• Reach the runtime API without relying on a separate ambient .d.ts package
• Get IDE-friendly imports (iconv.convert, idp.Client, …) instead of unmemorable tailor.iconv.convert(...) calls
• Use the same module surface in resolvers, executors, and workflows

The wrappers and their associated types are self-contained — you do not need to activate any ambient globals to use them. If you also want tailor.iconv.convert(...) calls to type-check, opt into the globals via the Activating the global types section below.

Quick Start

import {
  iconv,
  secretmanager,
  authconnection,
  idp,
  workflow,
  context,
  file,
} from "@tailor-platform/sdk/runtime";

const utf8 = iconv.convert(sjisBuffer, "Shift_JIS", "UTF-8");

const apiKey = await secretmanager.getSecret("my-vault", "API_KEY");

const token = await authconnection.getConnectionToken("google");

const client = new idp.Client({ namespace: "my-namespace" });
const { users } = await client.users({ first: 10 });

const executionId = await workflow.triggerWorkflow("approval", { reportId });

const invoker = context.getInvoker();

const { metadata } = await file.upload("my-namespace", "Document", "attachment", recordId, bytes);

Subpath imports

Each namespace can also be imported individually so you only pull what you need:

import * as iconv from "@tailor-platform/sdk/runtime/iconv";
import type { ListUsersResponse, ClientConfig } from "@tailor-platform/sdk/runtime/idp";

Activating the global types

Most users do not need to touch the globals entry — @tailor-platform/sdk/runtime (and its subpath modules) cover the same surface without depending on any ambient declaration.

For backwards compatibility with the previous @tailor-platform/function-types-based setup, the SDK still activates the ambient tailor.* / tailordb.* types automatically when you import from @tailor-platform/sdk. This implicit activation will be removed in v2.0; new code should prefer the typed wrappers from @tailor-platform/sdk/runtime.

If you want to opt into the globals explicitly (or you are migrating ahead of v2.0), add a single side-effect import anywhere in your project:

import "@tailor-platform/sdk/runtime/globals";

Or register the entry in tsconfig.json:

{
  "compilerOptions": {
    "types": ["@tailor-platform/sdk/runtime/globals"],
  },
}

Namespaces

The runtime entry re-exports the following namespaces. Detailed signatures, parameters, and return types live in the JSDoc next to each export — hover the symbol in your IDE or browse the source.

• iconv — character encoding conversion (convert, convertBuffer, decode, encode, encodings, Iconv)
• secretmanager — secret-vault access (getSecret, getSecrets)
• authconnection — OAuth-style connection tokens (getConnectionToken)
• idp — IdP user management (new Client({ namespace }))
• workflow — workflow & job control (triggerWorkflow, triggerJobFunction, wait, resolve)
• context — execution context (getInvoker)
• file — tailordb.file BLOB API (upload, download, downloadAsBase64, delete, getMetadata, openDownloadStream)

Testing

@tailor-platform/sdk/vitest ships mock controllers for every runtime namespace. Pair them with the tailor-runtime Vitest environment so your unit tests run against the same wrappers your production code does.

import { iconv, secretmanager } from "@tailor-platform/sdk/runtime";
import { iconvMock, secretmanagerMock } from "@tailor-platform/sdk/vitest";
import { beforeEach, expect, test } from "vitest";

beforeEach(() => {
  iconvMock.reset();
  secretmanagerMock.reset();
});

test("encodes via iconv", () => {
  iconvMock.setResolver(() => new Uint8Array([0x82, 0xa0]));

  const out = iconv.convert("あ", "UTF-8", "Shift_JIS");

  expect(out).toEqual(new Uint8Array([0x82, 0xa0]));
  expect(iconvMock.calls[0]?.method).toBe("convert");
});

test("reads from a vault", async () => {
  secretmanagerMock.setSecrets({ "my-vault": { API_KEY: "sk-123" } });

  await expect(secretmanager.getSecret("my-vault", "API_KEY")).resolves.toBe("sk-123");
});

See Testing Guide for the full list of mock controllers and the tailor-runtime environment setup.