@apicrafthq/script-sdk 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Florian Varrin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,50 @@
+# @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.
+
+> **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
+
+```sh
+bun add -D @apicrafthq/script-sdk
+# or
+pnpm add -D @apicrafthq/script-sdk
+# or
+npm i -D @apicrafthq/script-sdk
+```
+
+## Usage
+
+```ts
+import type { BeforeRequestContext } from '@apicrafthq/script-sdk';
+
+export const addAuthHeader = async (ctx: BeforeRequestContext) => {
+  const token = await ctx.var('AUTH_TOKEN');
+  ctx.request.headers['Authorization'] = `Bearer ${token}`;
+};
+```
+
+Response middleware:
+
+```ts
+import type { AfterResponseContext } from '@apicrafthq/script-sdk';
+
+export const logStatus = async (ctx: AfterResponseContext) => {
+  ctx.logger.info(`Response status: ${ctx.response.status}`);
+};
+```
+
+## `expect` for assertions
+
+The `expect` helper is available via a separate subpath so the main entry stays dependency-free:
+
+```ts
+import { expect } from '@apicrafthq/script-sdk/testing';
+
+expect(ctx.response.status).toBe(200);
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,115 @@
+/** HTTP client for auxiliary requests (login, remote signing, polling). */
+interface HttpClient {
+    get(url: string, init?: HttpRequestInit): Promise<HttpResponse>;
+    post(url: string, init?: HttpRequestInit): Promise<HttpResponse>;
+    put(url: string, init?: HttpRequestInit): Promise<HttpResponse>;
+    patch(url: string, init?: HttpRequestInit): Promise<HttpResponse>;
+    delete(url: string, init?: HttpRequestInit): Promise<HttpResponse>;
+}
+interface HttpRequestInit {
+    headers?: Record<string, string>;
+    /** Serialized according to the Content-Type. */
+    body?: unknown;
+    query?: Record<string, string>;
+}
+interface HttpResponse {
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    /** Parsed JSON when possible, otherwise a string. */
+    body: unknown;
+}
+/** Persistent key/value store across executions. */
+interface ScriptCache {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set<T = unknown>(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+/** Logger for scripts. Use this instead of `console`, which is not allowed. */
+interface ScriptLogger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+
+interface EnvSchema {
+}
+type EnvVarName = keyof EnvSchema extends never ? string : keyof EnvSchema | (string & {});
+type EnvVarReturn<K> = K extends keyof EnvSchema ? EnvSchema[K] : string | undefined;
+/** Primitives available to every script. */
+interface BaseContext {
+    /** Reads a variable from the environment. */
+    var<K extends EnvVarName>(name: K): EnvVarReturn<K>;
+    /** HTTP client for auxiliary requests (login, remote signing, polling). */
+    http: HttpClient;
+    /** Logger. Use instead of `console`, which is not allowed. */
+    logger: ScriptLogger;
+}
+
+/** Shared base for auth and middleware scripts. */
+interface RequestScopedContext extends BaseContext {
+    /** Persistent key/value store, shared across the project's request scripts. */
+    cache: ScriptCache;
+}
+/** Context for a before-middleware. Mutate `request` in place. */
+interface BeforeRequestContext extends RequestScopedContext {
+    request: MutableResolvedRequest;
+}
+/** Context for an after-middleware. `request` is read-only; mutate `response`. */
+interface AfterResponseContext extends RequestScopedContext {
+    readonly request: Readonly<ResolvedRequest>;
+    response: HttpResponse;
+}
+interface MutableResolvedRequest {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    query: Record<string, string>;
+    body?: unknown;
+}
+interface ResolvedRequest {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    query: Record<string, string>;
+    body?: unknown;
+}
+
+/** Shared base for workflow scripts (assert, condition, script). */
+interface WorkflowScopedContext extends BaseContext {
+    /** Reads the result of a previous block by its id. */
+    blockResult(blockId: string): BlockResult;
+    /** Writes a variable available to later blocks. */
+    setVar(name: string, value: unknown): void;
+    /** Runs an existing request instance and returns its response. */
+    executeRequest(resource: string, instance: string, overrides?: RequestOverrides): Promise<HttpResponse>;
+    /** Non-blocking pause, e.g. for polling. */
+    sleep(milliseconds: number): Promise<void>;
+}
+interface BlockResult {
+    /** Present for `request` blocks. */
+    response?: HttpResponse;
+    [key: string]: unknown;
+}
+interface RequestOverrides {
+    params?: {
+        path?: Record<string, string>;
+        query?: Record<string, string>;
+        header?: Record<string, string>;
+    };
+    body?: {
+        data?: unknown;
+    };
+}
+/** Context for an assert script. Throw to fail the assertion. */
+interface AssertContext extends WorkflowScopedContext {
+}
+/** Context for a condition script. Return a boolean to pick then/else. */
+interface ConditionContext extends WorkflowScopedContext {
+}
+/** Context for a free-form script block. */
+interface ScriptContext extends WorkflowScopedContext {
+}
+
+export type { AfterResponseContext, AssertContext, BaseContext, BeforeRequestContext, BlockResult, ConditionContext, EnvSchema, HttpClient, HttpRequestInit, HttpResponse, MutableResolvedRequest, RequestOverrides, RequestScopedContext, ResolvedRequest, ScriptCache, ScriptContext, ScriptLogger, WorkflowScopedContext };

package/dist/testing.d.ts

@@ -0,0 +1,5 @@
+import { ExpectStatic } from '@vitest/expect';
+
+declare const expect: ExpectStatic;
+
+export { expect };

package/dist/testing.js

@@ -0,0 +1,10 @@
+// src/expect.ts
+import * as chai from "chai";
+import { JestExtend, JestChaiExpect, JestAsymmetricMatchers } from "@vitest/expect";
+chai.use(JestExtend);
+chai.use(JestChaiExpect);
+chai.use(JestAsymmetricMatchers);
+var expect2 = chai.expect;
+export {
+  expect2 as expect
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@apicrafthq/script-sdk",
+  "version": "0.1.0-beta.0",
+  "type": "module",
+  "description": "TypeScript types for API Craft middleware and custom-auth scripts.",
+  "license": "MIT",
+  "author": "Florian Varrin",
+  "homepage": "https://github.com/fvarrin/api-craft#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fvarrin/api-craft.git",
+    "directory": "packages/script-sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/fvarrin/api-craft/issues"
+  },
+  "keywords": [
+    "api-craft",
+    "sdk",
+    "middleware",
+    "types",
+    "http",
+    "typescript"
+  ],
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    }
+  },
+  "devDependencies": {
+    "@types/chai": "^5.2.0",
+    "tsup": "^8",
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@vitest/expect": "^3.2.0",
+    "chai": "^5.1.2"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/testing.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts src/testing.ts --format esm --dts --watch"
+  }
+}