@apicrafthq/script-sdk

TypeScript types for API Craft scripts. Use it to get autocomplete and type-checking for the ctx argument in middleware, custom-auth handlers, and workflow script blocks.

Beta. API Craft is pre-1.0. Breaking changes may happen before the stable release. Pin to a specific beta version if you need stability.

Install

bun add -D @apicrafthq/script-sdk
# or
pnpm add -D @apicrafthq/script-sdk
# or
npm i -D @apicrafthq/script-sdk

The package is types-only: it has no runtime code and no dependencies.

Middleware and custom auth

Request middleware and custom-auth handlers receive a BeforeRequestContext. Mutate ctx.request in place:

import type { BeforeRequestContext } from '@apicrafthq/script-sdk';

export const addAuthHeader = async (ctx: BeforeRequestContext) => {
  const token = ctx.var('AUTH_TOKEN');
  ctx.request.headers['Authorization'] = `Bearer ${token}`;
};

Response middleware receives an AfterResponseContext. ctx.request is read-only; mutate ctx.response:

import type { AfterResponseContext } from '@apicrafthq/script-sdk';

export const logStatus = async (ctx: AfterResponseContext) => {
  ctx.logger.info(`Response status: ${ctx.response.status}`);
};

Every context also provides ctx.http (an HTTP client for auxiliary requests such as login or token refresh) and ctx.cache (a persistent key/value store shared across the project's request scripts).

Options

A script file can export an options constant describing configurable options per exported function. API Craft renders them as a form when the function is attached, stores the chosen values on the attached ref, and passes them as ctx.options:

import type { AfterResponseContext, InferOptions, OptionsMap } from '@apicrafthq/script-sdk';

export const options = {
  byStatus: {
    status: { type: 'integer', title: 'Expected status', enum: [200, 201, 204, 404], default: 200 },
    onMismatch: { type: 'string', enum: ['fail', 'warn'], default: 'fail' },
  },
} as const satisfies OptionsMap;

export const byStatus = async (ctx: AfterResponseContext<InferOptions<typeof options.byStatus>>) => {
  if (ctx.response.status === ctx.options.status) return;
  const message = `Expected ${ctx.options.status}, got ${ctx.response.status}`;
  if (ctx.options.onMismatch === 'warn') return ctx.logger.warn(message);
  throw new Error(message);
};

Each option is a small JSON Schema: type (string, integer, number, boolean), optional enum, default, title, description, and required: true. InferOptions derives the ctx.options type: a key with required: true or a default is always present, the others are optional. Values are validated against the schema before the script runs.

Workflow scripts

Workflow blocks have their own contexts: AssertContext, ConditionContext, TransformContext, and ScriptContext. They expose ctx.blockResult(blockId) to read previous block outputs and ctx.env(apiSlug) for the resolved environment of a bound API:

import type { TransformContext } from '@apicrafthq/script-sdk';

export const extractUserId = async (ctx: TransformContext) => {
  const { response } = ctx.blockResult('create-user');
  return { userId: response.body.id };
};

An assert script fails by throwing; a condition script returns a boolean; a transform script returns an object whose keys become the block's outputs. Free-form ScriptContext blocks additionally get ctx.sleep(milliseconds) for polling.

License

MIT