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

package/README.md

@@ -41,6 +41,30 @@ export const logStatus = async (ctx: AfterResponseContext) => {
 
 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.
+
 ## 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:

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.6",
+  "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": {
     ".": {