@apicrafthq/script-sdk 0.1.0-beta.5 → 0.1.0-beta.7

package/README.md

@@ -1,6 +1,6 @@
 # @apicrafthq/script-sdk
 
-TypeScript types for [API Craft](https://github.com/fvarrin/api-craft) middleware and custom-auth scripts. Use it to get autocomplete and type-checking for the `ctx` argument in your `before` / `after` request hooks and custom auth handlers.
+TypeScript types for [API Craft](https://github.com/fvarrin/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.
 
@@ -14,18 +14,22 @@ pnpm add -D @apicrafthq/script-sdk
 npm i -D @apicrafthq/script-sdk
 ```
 
-## Usage
+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:
 
 ```ts
 import type { BeforeRequestContext } from '@apicrafthq/script-sdk';
 
 export const addAuthHeader = async (ctx: BeforeRequestContext) => {
-  const token = await ctx.var('AUTH_TOKEN');
+  const token = ctx.var('AUTH_TOKEN');
   ctx.request.headers['Authorization'] = `Bearer ${token}`;
 };
 ```
 
-Response middleware:
+Response middleware receives an `AfterResponseContext`. `ctx.request` is read-only; mutate `ctx.response`:
 
 ```ts
 import type { AfterResponseContext } from '@apicrafthq/script-sdk';
@@ -35,16 +39,47 @@ export const logStatus = async (ctx: AfterResponseContext) => {
 };
 ```
 
-## `expect` for assertions
+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`:
+
+```ts
+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.
 
-The `expect` helper is available via a separate subpath so the main entry stays dependency-free:
+## 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:
 
 ```ts
-import { expect } from '@apicrafthq/script-sdk/testing';
+import type { TransformContext } from '@apicrafthq/script-sdk';
 
-expect(ctx.response.status).toBe(200);
+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

package/dist/index.d.ts

@@ -60,13 +60,17 @@ interface RequestScopedContext extends BaseContext {
     cache: ScriptCache;
 }
 /** Context for a before-middleware. Mutate `request` in place. */
-interface BeforeRequestContext extends RequestScopedContext {
+interface BeforeRequestContext<O = Record<string, never>> extends RequestScopedContext {
     request: MutableResolvedRequest;
+    /** Options declared by the script's `options` export, as configured on the attached ref. */
+    readonly options: O;
 }
 /** Context for an after-middleware. `request` is read-only; mutate `response`. */
-interface AfterResponseContext extends RequestScopedContext {
+interface AfterResponseContext<O = Record<string, never>> extends RequestScopedContext {
     readonly request: Readonly<ResolvedRequest>;
     response: HttpResponse;
+    /** Options declared by the script's `options` export, as configured on the attached ref. */
+    readonly options: O;
 }
 interface MutableResolvedRequest {
     method: string;
@@ -83,6 +87,57 @@ interface ResolvedRequest {
     body?: unknown;
 }
 
+/** Declarable option, a subset of JSON Schema. Rendered as a form field by API Craft. */
+type OptionSchema = {
+    type: 'string';
+    enum?: readonly string[];
+    default?: string;
+    title?: string;
+    description?: string;
+    required?: boolean;
+} | {
+    type: 'integer' | 'number';
+    enum?: readonly number[];
+    default?: number;
+    title?: string;
+    description?: string;
+    required?: boolean;
+} | {
+    type: 'boolean';
+    default?: boolean;
+    title?: string;
+    description?: string;
+    required?: boolean;
+};
+/** Options declared by a script file, keyed by exported function name. */
+type OptionsMap = Record<string, Record<string, OptionSchema>>;
+type OptionValue<S extends OptionSchema> = S extends {
+    enum: readonly (infer E)[];
+} ? E : S extends {
+    type: 'string';
+} ? string : S extends {
+    type: 'integer' | 'number';
+} ? number : S extends {
+    type: 'boolean';
+} ? boolean : never;
+type IsProvidedKey<S extends OptionSchema> = S extends {
+    required: true;
+} ? true : S extends {
+    default: string | number | boolean;
+} ? true : false;
+type ProvidedKeys<S extends Record<string, OptionSchema>> = {
+    [K in keyof S]: IsProvidedKey<S[K]> extends true ? K : never;
+}[keyof S];
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/** Derives the `ctx.options` type from one entry of an {@link OptionsMap}. */
+type InferOptions<S extends Record<string, OptionSchema>> = Simplify<{
+    readonly [K in ProvidedKeys<S>]: OptionValue<S[K]>;
+} & {
+    readonly [K in Exclude<keyof S, ProvidedKeys<S>>]?: OptionValue<S[K]>;
+}>;
+
 /**
  * Known workflow block ids. Augmented per-API by the generated env.d.ts so
  * `blockResult(...)` autocompletes real block ids; falls back to `string`.
@@ -117,4 +172,4 @@ interface ScriptContext extends WorkflowScopedContext {
     sleep(milliseconds: number): Promise<void>;
 }
 
-export type { AfterResponseContext, AssertContext, BaseContext, BeforeRequestContext, BlockResult, BlockResultSchema, ConditionContext, EnvSchema, HttpClient, HttpRequestInit, HttpResponse, HttpResponseBody, MutableResolvedRequest, RequestScopedContext, ResolvedRequest, ScriptCache, ScriptContext, ScriptLogger, TransformContext, WorkflowScopedContext };
+export type { AfterResponseContext, AssertContext, BaseContext, BeforeRequestContext, BlockResult, BlockResultSchema, ConditionContext, EnvSchema, HttpClient, HttpRequestInit, HttpResponse, HttpResponseBody, InferOptions, MutableResolvedRequest, OptionSchema, OptionsMap, RequestScopedContext, ResolvedRequest, ScriptCache, ScriptContext, ScriptLogger, TransformContext, WorkflowScopedContext };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apicrafthq/script-sdk",
-  "version": "0.1.0-beta.5",
+  "version": "0.1.0-beta.7",
   "type": "module",
   "description": "TypeScript types for API Craft middleware and custom-auth scripts.",
   "license": "MIT",
@@ -24,8 +24,7 @@
     "LICENSE"
   ],
   "publishConfig": {
-    "access": "public",
-    "tag": "beta"
+    "access": "public"
   },
   "exports": {
     ".": {