@ptkl/sdk 1.17.1 → 1.18.1

package/dist/index.0.10.js

@@ -1628,18 +1628,51 @@ var ProtokolSDK010 = (function (exports, axios) {
             return await this.client.get(`/luma/appservice/v1/forge/${ref}/services`);
         }
         // --- Variables ---
+        /**
+         * Build the variables path for a target app.
+         *
+         * Omitting `ref` selects the pathless self route, where the server resolves the
+         * app from the caller's own token. That is why the self forms work in every
+         * context an app token does, including Node, where `resolveCurrentAppUuid()`
+         * has nothing to read.
+         */
+        variablesPath(ref) {
+            return ref
+                ? `/luma/appservice/v1/forge/${encodeURIComponent(ref)}/variables`
+                : `/luma/appservice/v1/forge/variables`;
+        }
+        /**
+         * Read variables for the current environment (`X-Project-Env`, defaults to dev).
+         *
+         * With no argument this returns the CALLING APP's own variables and needs no
+         * permission at all. With a `ref` it reads that app's variables and needs
+         * `manage forge`.
+         *
+         * @param ref App uuid, name or tag. Omit for the current app.
+         *
+         * @example
+         * const mine = await platform.forge().getVariables()
+         * const other = await platform.forge().getVariables('storefront')
+         */
         async getVariables(ref) {
-            return await this.client.get(`/luma/appservice/v1/forge/${ref}/variables`);
+            return await this.client.get(this.variablesPath(ref));
         }
-        async updateVariables(ref, variables) {
-            return await this.client.patch(`/luma/appservice/v1/forge/${ref}/variables`, variables);
+        async updateVariables(a, b) {
+            const [ref, variables] = typeof a === 'string'
+                ? [a, b]
+                : [undefined, a];
+            return await this.client.patch(this.variablesPath(ref), variables);
         }
-        async addVariable(ref, key, value) {
+        async addVariable(a, b, c) {
             var _a;
-            const resp = await this.client.get(`/luma/appservice/v1/forge/${ref}/variables`);
-            const current = (_a = resp.data) !== null && _a !== void 0 ? _a : {};
-            current[key] = value;
-            return await this.client.patch(`/luma/appservice/v1/forge/${ref}/variables`, current);
+            // Arity, not `c !== undefined` — otherwise addVariable('ref', 'KEY', undefined)
+            // is read as the two-argument self form and writes a variable named "ref".
+            const [ref, key, value] = arguments.length >= 3
+                ? [a, b, c]
+                : [undefined, a, b];
+            const path = this.variablesPath(ref);
+            const resp = await this.client.get(path);
+            return await this.client.patch(path, { ...((_a = resp.data) !== null && _a !== void 0 ? _a : {}), [key]: value });
         }
         // --- Service execution (forge-runtime) ---
         /**
@@ -1799,22 +1832,29 @@ var ProtokolSDK010 = (function (exports, axios) {
         // Stateless completion — no conversation is created and nothing is
         // persisted. The caller owns the message list.
         //
-        // Always responds with an SSE stream (message_start, thinking_delta,
-        // content_delta, message_complete, error). Tool calls are surfaced in
+        // Returns the raw SSE body as a string: events separated by blank lines,
+        // each `event: <name>` + `data: <json>`. Tool calls arrive in
         // message_complete for client-side execution; post the results back as
         // messages with role 'tool' and the matching tool_call_id.
         //
+        // NOT typed as a stream, deliberately. This SDK is executed inside
+        // isolated-vm sandboxes (the eval server runs the bundle in-isolate and
+        // proxies HTTP through an adapter), and every value crossing that boundary
+        // is structure-cloned. A Node Readable carries internal callbacks and dies
+        // there with "could not be cloned" — an error that points nowhere near the
+        // method that caused it. Buffering keeps this binding usable everywhere.
+        //
+        // A consumer that genuinely needs incremental delivery should drive the
+        // endpoint directly rather than through the SDK, as the kortex CLI does.
+        //
         // Constraints enforced server-side: agent_uuid is required, the last
         // message must have role 'user', 'context' or 'tool', and no message
         // content may exceed 32000 bytes.
-        //
-        // Typed as a Node stream because that is what axios `responseType:
-        // 'stream'` yields under Node, which is where this binding is used.
-        // Browser callers should drive the endpoint with fetch directly rather
-        // than through axios.
         async chat(data) {
             return await this.client.post(`${BASE$1}/chat`, data, {
-                responseType: 'stream',
+                responseType: 'text',
+                // Keep the SSE body intact — the default transform attempts JSON.parse.
+                transformResponse: [(body) => body],
                 timeout: 120000,
             });
         }

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ptkl/sdk",
-  "version": "1.17.1",
+  "version": "1.18.1",
   "scripts": {
     "build": "rollup -c",
     "build:monaco": "npm run build && node scripts/generate-monaco-types.cjs",

package/dist/v0.10/api/forge.d.ts

@@ -1,12 +1,61 @@
 import PlatformBaseClient from "./platformBaseClient";
+import type { ForgeVariables } from "../types/forge";
 export default class Forge extends PlatformBaseClient {
     bundleUpload(buffer: Buffer): Promise<any>;
     getWorkspaceApps(): Promise<any>;
     removeVersion(ref: string, version: string): Promise<any>;
     list(): Promise<any>;
     listServices(ref: string): Promise<any>;
-    getVariables(ref: string): Promise<any>;
-    updateVariables(ref: string, variables: Record<string, any>): Promise<any>;
+    /**
+     * Build the variables path for a target app.
+     *
+     * Omitting `ref` selects the pathless self route, where the server resolves the
+     * app from the caller's own token. That is why the self forms work in every
+     * context an app token does, including Node, where `resolveCurrentAppUuid()`
+     * has nothing to read.
+     */
+    private variablesPath;
+    /**
+     * Read variables for the current environment (`X-Project-Env`, defaults to dev).
+     *
+     * With no argument this returns the CALLING APP's own variables and needs no
+     * permission at all. With a `ref` it reads that app's variables and needs
+     * `manage forge`.
+     *
+     * @param ref App uuid, name or tag. Omit for the current app.
+     *
+     * @example
+     * const mine = await platform.forge().getVariables()
+     * const other = await platform.forge().getVariables('storefront')
+     */
+    getVariables(ref?: string): Promise<any>;
+    /**
+     * Replace the variable set for the current environment.
+     *
+     * This REPLACES the whole set for that environment — keys absent from
+     * `variables` are removed. The other environment is left untouched.
+     *
+     * The self form needs `manage_variables forge`, which only ever writes the
+     * calling app. Targeting another app by `ref` needs `manage forge`.
+     *
+     * @example
+     * await platform.forge().updateVariables({ WEBHOOK_URL: '...' })
+     * await platform.forge().updateVariables('storefront', { WEBHOOK_URL: '...' })
+     */
+    updateVariables(variables: ForgeVariables): Promise<any>;
+    updateVariables(ref: string, variables: ForgeVariables): Promise<any>;
+    /**
+     * Set a single variable, preserving the rest.
+     *
+     * A read-modify-write over a replace-everything PATCH, so concurrent writers
+     * can lose each other's updates. Prefer `updateVariables` when setting more
+     * than one key.
+     *
+     * @example
+     * await platform.forge().addVariable('WEBHOOK_URL', '...')
+     * await platform.forge().addVariable('storefront', 'WEBHOOK_URL', '...')
+     */
+    addVariable(key: string, value: any): Promise<any>;
     addVariable(ref: string, key: string, value: any): Promise<any>;
     /**
      * Run a Forge service: `runService(target, body?, { query?, headers? })`.

package/dist/v0.10/api/index.d.ts

@@ -17,6 +17,7 @@ export { default as Sandbox } from './sandbox';
 export { default as System } from './system';
 export { default as Workflow } from './workflow';
 export { default as Forge } from './forge';
+export type { ForgeVariables } from '../types/forge';
 export { default as Kortex } from './kortex';
 export { default as Project } from './project';
 export { default as Config } from './config';

package/dist/v0.10/api/kortex.d.ts

@@ -35,7 +35,7 @@ export default class Kortex extends PlatformBaseClient {
     streamMessage(conversationUUID: string, data: SendMessagePayload): Promise<AxiosResponse<ReadableStream>>;
     listMessages(conversationUUID: string, params?: PaginationParams): Promise<AxiosResponse<PagedResponse<Message>>>;
     injectMessage(conversationUUID: string, data: InjectMessagePayload): Promise<AxiosResponse<Message>>;
-    chat(data: KortexChatPayload): Promise<AxiosResponse<NodeJS.ReadableStream>>;
+    chat(data: KortexChatPayload): Promise<AxiosResponse<string>>;
     ocr(data: OCRPayload): Promise<AxiosResponse<OCRResult>>;
     createUserAccess(data: UserAccessCreatePayload): Promise<AxiosResponse<UserAccess>>;
     listUserAccess(params?: PaginationParams): Promise<AxiosResponse<PagedResponse<UserAccess>>>;

package/dist/v0.10/index.cjs.js

@@ -20594,18 +20594,51 @@ class Forge extends PlatformBaseClient {
         return await this.client.get(`/luma/appservice/v1/forge/${ref}/services`);
     }
     // --- Variables ---
+    /**
+     * Build the variables path for a target app.
+     *
+     * Omitting `ref` selects the pathless self route, where the server resolves the
+     * app from the caller's own token. That is why the self forms work in every
+     * context an app token does, including Node, where `resolveCurrentAppUuid()`
+     * has nothing to read.
+     */
+    variablesPath(ref) {
+        return ref
+            ? `/luma/appservice/v1/forge/${encodeURIComponent(ref)}/variables`
+            : `/luma/appservice/v1/forge/variables`;
+    }
+    /**
+     * Read variables for the current environment (`X-Project-Env`, defaults to dev).
+     *
+     * With no argument this returns the CALLING APP's own variables and needs no
+     * permission at all. With a `ref` it reads that app's variables and needs
+     * `manage forge`.
+     *
+     * @param ref App uuid, name or tag. Omit for the current app.
+     *
+     * @example
+     * const mine = await platform.forge().getVariables()
+     * const other = await platform.forge().getVariables('storefront')
+     */
     async getVariables(ref) {
-        return await this.client.get(`/luma/appservice/v1/forge/${ref}/variables`);
+        return await this.client.get(this.variablesPath(ref));
     }
-    async updateVariables(ref, variables) {
-        return await this.client.patch(`/luma/appservice/v1/forge/${ref}/variables`, variables);
+    async updateVariables(a, b) {
+        const [ref, variables] = typeof a === 'string'
+            ? [a, b]
+            : [undefined, a];
+        return await this.client.patch(this.variablesPath(ref), variables);
     }
-    async addVariable(ref, key, value) {
+    async addVariable(a, b, c) {
         var _a;
-        const resp = await this.client.get(`/luma/appservice/v1/forge/${ref}/variables`);
-        const current = (_a = resp.data) !== null && _a !== void 0 ? _a : {};
-        current[key] = value;
-        return await this.client.patch(`/luma/appservice/v1/forge/${ref}/variables`, current);
+        // Arity, not `c !== undefined` — otherwise addVariable('ref', 'KEY', undefined)
+        // is read as the two-argument self form and writes a variable named "ref".
+        const [ref, key, value] = arguments.length >= 3
+            ? [a, b, c]
+            : [undefined, a, b];
+        const path = this.variablesPath(ref);
+        const resp = await this.client.get(path);
+        return await this.client.patch(path, { ...((_a = resp.data) !== null && _a !== void 0 ? _a : {}), [key]: value });
     }
     // --- Service execution (forge-runtime) ---
     /**
@@ -20765,22 +20798,29 @@ class Kortex extends PlatformBaseClient {
     // Stateless completion — no conversation is created and nothing is
     // persisted. The caller owns the message list.
     //
-    // Always responds with an SSE stream (message_start, thinking_delta,
-    // content_delta, message_complete, error). Tool calls are surfaced in
+    // Returns the raw SSE body as a string: events separated by blank lines,
+    // each `event: <name>` + `data: <json>`. Tool calls arrive in
     // message_complete for client-side execution; post the results back as
     // messages with role 'tool' and the matching tool_call_id.
     //
+    // NOT typed as a stream, deliberately. This SDK is executed inside
+    // isolated-vm sandboxes (the eval server runs the bundle in-isolate and
+    // proxies HTTP through an adapter), and every value crossing that boundary
+    // is structure-cloned. A Node Readable carries internal callbacks and dies
+    // there with "could not be cloned" — an error that points nowhere near the
+    // method that caused it. Buffering keeps this binding usable everywhere.
+    //
+    // A consumer that genuinely needs incremental delivery should drive the
+    // endpoint directly rather than through the SDK, as the kortex CLI does.
+    //
     // Constraints enforced server-side: agent_uuid is required, the last
     // message must have role 'user', 'context' or 'tool', and no message
     // content may exceed 32000 bytes.
-    //
-    // Typed as a Node stream because that is what axios `responseType:
-    // 'stream'` yields under Node, which is where this binding is used.
-    // Browser callers should drive the endpoint with fetch directly rather
-    // than through axios.
     async chat(data) {
         return await this.client.post(`${BASE$1}/chat`, data, {
-            responseType: 'stream',
+            responseType: 'text',
+            // Keep the SSE body intact — the default transform attempts JSON.parse.
+            transformResponse: [(body) => body],
             timeout: 120000,
         });
     }

package/dist/v0.10/index.esm.js

@@ -1627,18 +1627,51 @@ class Forge extends PlatformBaseClient {
         return await this.client.get(`/luma/appservice/v1/forge/${ref}/services`);
     }
     // --- Variables ---
+    /**
+     * Build the variables path for a target app.
+     *
+     * Omitting `ref` selects the pathless self route, where the server resolves the
+     * app from the caller's own token. That is why the self forms work in every
+     * context an app token does, including Node, where `resolveCurrentAppUuid()`
+     * has nothing to read.
+     */
+    variablesPath(ref) {
+        return ref
+            ? `/luma/appservice/v1/forge/${encodeURIComponent(ref)}/variables`
+            : `/luma/appservice/v1/forge/variables`;
+    }
+    /**
+     * Read variables for the current environment (`X-Project-Env`, defaults to dev).
+     *
+     * With no argument this returns the CALLING APP's own variables and needs no
+     * permission at all. With a `ref` it reads that app's variables and needs
+     * `manage forge`.
+     *
+     * @param ref App uuid, name or tag. Omit for the current app.
+     *
+     * @example
+     * const mine = await platform.forge().getVariables()
+     * const other = await platform.forge().getVariables('storefront')
+     */
     async getVariables(ref) {
-        return await this.client.get(`/luma/appservice/v1/forge/${ref}/variables`);
+        return await this.client.get(this.variablesPath(ref));
     }
-    async updateVariables(ref, variables) {
-        return await this.client.patch(`/luma/appservice/v1/forge/${ref}/variables`, variables);
+    async updateVariables(a, b) {
+        const [ref, variables] = typeof a === 'string'
+            ? [a, b]
+            : [undefined, a];
+        return await this.client.patch(this.variablesPath(ref), variables);
     }
-    async addVariable(ref, key, value) {
+    async addVariable(a, b, c) {
         var _a;
-        const resp = await this.client.get(`/luma/appservice/v1/forge/${ref}/variables`);
-        const current = (_a = resp.data) !== null && _a !== void 0 ? _a : {};
-        current[key] = value;
-        return await this.client.patch(`/luma/appservice/v1/forge/${ref}/variables`, current);
+        // Arity, not `c !== undefined` — otherwise addVariable('ref', 'KEY', undefined)
+        // is read as the two-argument self form and writes a variable named "ref".
+        const [ref, key, value] = arguments.length >= 3
+            ? [a, b, c]
+            : [undefined, a, b];
+        const path = this.variablesPath(ref);
+        const resp = await this.client.get(path);
+        return await this.client.patch(path, { ...((_a = resp.data) !== null && _a !== void 0 ? _a : {}), [key]: value });
     }
     // --- Service execution (forge-runtime) ---
     /**
@@ -1798,22 +1831,29 @@ class Kortex extends PlatformBaseClient {
     // Stateless completion — no conversation is created and nothing is
     // persisted. The caller owns the message list.
     //
-    // Always responds with an SSE stream (message_start, thinking_delta,
-    // content_delta, message_complete, error). Tool calls are surfaced in
+    // Returns the raw SSE body as a string: events separated by blank lines,
+    // each `event: <name>` + `data: <json>`. Tool calls arrive in
     // message_complete for client-side execution; post the results back as
     // messages with role 'tool' and the matching tool_call_id.
     //
+    // NOT typed as a stream, deliberately. This SDK is executed inside
+    // isolated-vm sandboxes (the eval server runs the bundle in-isolate and
+    // proxies HTTP through an adapter), and every value crossing that boundary
+    // is structure-cloned. A Node Readable carries internal callbacks and dies
+    // there with "could not be cloned" — an error that points nowhere near the
+    // method that caused it. Buffering keeps this binding usable everywhere.
+    //
+    // A consumer that genuinely needs incremental delivery should drive the
+    // endpoint directly rather than through the SDK, as the kortex CLI does.
+    //
     // Constraints enforced server-side: agent_uuid is required, the last
     // message must have role 'user', 'context' or 'tool', and no message
     // content may exceed 32000 bytes.
-    //
-    // Typed as a Node stream because that is what axios `responseType:
-    // 'stream'` yields under Node, which is where this binding is used.
-    // Browser callers should drive the endpoint with fetch directly rather
-    // than through axios.
     async chat(data) {
         return await this.client.post(`${BASE$1}/chat`, data, {
-            responseType: 'stream',
+            responseType: 'text',
+            // Keep the SSE body intact — the default transform attempts JSON.parse.
+            transformResponse: [(body) => body],
             timeout: 120000,
         });
     }

package/dist/v0.10/types/component.d.ts

@@ -251,10 +251,20 @@ type FieldConstraints = {
     unique?: boolean;
     placeholder?: string;
     default?: string;
+    /** Bounds the *length* of a string value (input/text, password, ...). */
     length?: {
         min?: number | null;
         max?: number | null;
     };
+    /**
+     * Bounds the *value* of a numeric field (input/number). Inclusive on both
+     * ends. Prefer this over `length` for numbers — `length` is only still read
+     * as a fallback for fields authored before `range` existed.
+     */
+    range?: {
+        min?: number | null;
+        max?: number | null;
+    };
     not_allowed_words?: string;
     regex?: string;
     date?: {

package/dist/v0.10/types/forge.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A Forge app's variables for a single environment: a flat, JSON-serialisable
+ * key/value map.
+ *
+ * Each app holds two independent sets, `dev` and `live`. Which one an API call
+ * reads or writes is selected by the `X-Project-Env` header, not by this type.
+ *
+ * @example
+ * const vars: ForgeVariables = { WEBHOOK_URL: 'https://example.com/hook', MAX_RETRIES: 3 }
+ */
+export type ForgeVariables = Record<string, any>;

package/dist/v0.10/types/thunder.d.ts

@@ -1,4 +1,18 @@
 export type ThunderReadOptions = {
+    /**
+     * Maximum age, in seconds, of a cached response you are willing to accept.
+     *
+     * - omitted — serve whatever is cached, regardless of age (Thunder's
+     *   historical behaviour, and still the cheapest read)
+     * - `0` — skip the cache and read from the database
+     * - `> 0` — serve a cached response only if it is younger than this many
+     *   seconds, otherwise refresh from the database
+     *
+     * Not clamped: `1` and `86400` are both honoured.
+     *
+     * Note this differs from the component read option of the same name, where
+     * an omitted value behaves like `0` and the value is clamped to 5-300s.
+     */
     cacheTTL?: number;
     only?: string[];
 };

package/dist/v0.9/types/component.d.ts

@@ -221,10 +221,20 @@ type FieldConstraints = {
     unique?: boolean;
     placeholder?: string;
     default?: string;
+    /** Bounds the *length* of a string value (input/text, password, ...). */
     length?: {
         min?: number | null;
         max?: number | null;
     };
+    /**
+     * Bounds the *value* of a numeric field (input/number). Inclusive on both
+     * ends. Prefer this over `length` for numbers — `length` is only still read
+     * as a fallback for fields authored before `range` existed.
+     */
+    range?: {
+        min?: number | null;
+        max?: number | null;
+    };
     not_allowed_words?: string;
     regex?: string;
     date?: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ptkl/sdk",
-  "version": "1.17.1",
+  "version": "1.18.1",
   "scripts": {
     "build": "rollup -c",
     "build:monaco": "npm run build && node scripts/generate-monaco-types.cjs",