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

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,23 @@ 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).
+
+## Workflow scripts
 
-The `expect` helper is available via a separate subpath so the main entry stays dependency-free:
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apicrafthq/script-sdk",
-  "version": "0.1.0-beta.5",
+  "version": "0.1.0-beta.6",
   "type": "module",
   "description": "TypeScript types for API Craft middleware and custom-auth scripts.",
   "license": "MIT",