@simpleplatform/sdk 2.1.0 → 2.3.0

package/README.md

@@ -40,7 +40,7 @@ The TypeScript SDK is organized into focused modules for different capabilities:
 | **Security** | `@simpleplatform/sdk/security` | Security policy authoring                      |
 | **Settings** | `@simpleplatform/sdk/settings` | Application settings retrieval                 |
 | **Storage**  | `@simpleplatform/sdk/storage`  | File upload, and reading a stored file's bytes |
-| **Space**    | `@simpleplatform/sdk/space`    | Behavior-aware record workflows in a Space     |
+| **Space**    | `@simpleplatform/sdk/space`    | Records, data, tasks, and documents in a Space |
 
 ## Embedded Spaces
 
@@ -100,6 +100,10 @@ and tools. In a non-record Space, `simple.data` remains available while
 `simple.records.current()` rejects with `SpaceProtocolError` code `unavailable`
 and explains that the Space must be configured as a record view.
 
+Each capability beyond `simple.data` is negotiated with the host when the Space
+connects. A capability the host did not negotiate rejects with
+`SpaceProtocolError` code `unavailable` when it is called, and sends nothing.
+
 ### Space data access
 
 Use `simple.data` for application data that is not the record form currently
@@ -131,6 +135,175 @@ Those commands preserve Record Behaviors, validation, documents, and the shared
 record state used by the platform header. `simple.data.mutate()` is for other
 authorized application data; it must not be used to bypass a record workflow.
 
+### Space tasks
+
+`simple.tasks` creates a task from a task type and replies on a task. Tasks are
+not the page's record, so they work in standalone and record Spaces alike.
+
+```typescript
+const { task } = await simple.tasks.create({
+  assignedToId: 'USR000005', // Optional: defaults to the user creating the task.
+  input: { packet: 'DOC000001' }, // The typed input the task type declares.
+  taskTypeId: 'TTY000003',
+  title: 'Review the contract packet',
+})
+
+const { messageId, taskRevision } = await simple.tasks.reply({
+  content: 'The revised drawing is attached.',
+  inReplyToMessageId: 'MSG000006', // Optional: the message this reply answers.
+  taskId: task.id,
+})
+```
+
+`create()` returns `{ task: { id, status, revision } }`, where `status` is one
+of `queued`, `in_progress`, `waiting`, `completed`, `cancelled`, or `failed`.
+`reply()` returns the new message's ID and the task's revision after the reply.
+
+`input` is always a JSON object; pass `{}` when the task type needs no input.
+Everything inside it must be a JSON value (plain objects, arrays, strings,
+finite numbers, booleans, and `null`) so it means the same thing on every
+transport. `null`, an array, or a single value as the input itself is refused.
+The host holds a task type's typed input to 32,768 encoded bytes and 64 levels
+of nesting.
+
+`assignedToId`, when given, must name an existing user in the tenant; left out,
+the task is assigned to the user creating it.
+
+A request the SDK can tell is incomplete is refused before it is sent, with
+`SpaceProtocolError` code `invalid_request`.
+
+When the task service refuses a create or a reply, the call rejects with
+`SpaceProtocolError` code `task_rejected`, whatever the reason. Its `message` is
+the service's message, and its `details` is the service's error exactly as sent:
+`{ code, category, message, pointers, details }`. Neither the host nor the SDK
+adds, drops, or renames anything in it. The reason is `details.code`, not
+`error.code`:
+
+```typescript
+import { SpaceProtocolError } from '@simpleplatform/sdk/space'
+
+try {
+  await simple.tasks.create({ input: { amount: 700 }, taskTypeId: 'TTY000003', title: 'Open the job' })
+}
+catch (error) {
+  if (!(error instanceof SpaceProtocolError) || error.code !== 'task_rejected')
+    throw error
+
+  const refusal = error.details as { category: string, code: string, details: unknown, pointers: string[] }
+  // refusal.category says whether to correct the request or send it again,
+  // refusal.code says why, and refusal.pointers says where.
+  console.warn(refusal.category, refusal.code, refusal.pointers)
+}
+```
+
+`details.category` says whether to correct the request or send it again:
+
+- `validation` is final. The request is wrong, and the host keeps nothing of
+  the refused create, so correct the request before sending it again.
+- `runtime` means the task service did not answer, not that the request is
+  wrong. Its codes are `TASK_RUNTIME_UNAVAILABLE`, `TASK_RUNTIME_TIMEOUT`,
+  `TASK_RUNTIME_BUSY`, and `TASK_RUNTIME_REMOTE_FAILURE`. The host keeps the
+  pending create, so calling `create()` again with the same arguments resends
+  that create under the same task id, and a create that did land is not made
+  twice.
+
+A create's title, input, and assignee are refused with these `validation`
+codes:
+
+| `details.code`          | When                                                                                  | `details.pointers`                                        | `details.details`                   |
+| ----------------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------- | ----------------------------------- |
+| `TASK_INPUT_INVALID`    | The input fails its task type's input schema                                          | Each issue's `instance_pointer` under `/input`, once each | `{ errors, truncated }`             |
+| `TASK_INPUT_INVALID`    | The title is longer than 255 characters, or the input is nested deeper than 64 levels | `/title` or `/input`                                      | `{}`                                |
+| `TASK_INPUT_TOO_LARGE`  | The input encodes to more than 32,768 bytes                                           | `/input`                                                  | `{ measured_bytes, allowed_bytes }` |
+| `TASK_ASSIGNEE_INVALID` | `assignedToId` is not a user in the tenant                                            | `/assigned_to_id`                                         | `{}`                                |
+
+For a schema failure, `errors` holds at most 50 issues sorted by
+`instance_pointer`, and `truncated` is `true` when there were more. Each issue
+is exactly `{ code, instance_pointer, schema_pointer }` and never carries the
+value that failed. `instance_pointer` is relative to the input, while
+`pointers` carries the `/input` prefix. `schema_pointer` is the location in the
+task type's input schema of the object holding the keyword that failed.
+
+For example, a task type whose input schema is
+`{ type: 'object', properties: { amount: { type: 'integer' } }, required: ['job_id'], additionalProperties: false }`
+refuses the input `{ amount: 'seven hundred', note: 'a private note' }` with
+this `error.details`:
+
+```json
+{
+  "code": "TASK_INPUT_INVALID",
+  "category": "validation",
+  "message": "The task input is invalid.",
+  "pointers": ["/input", "/input/amount", "/input/note"],
+  "details": {
+    "errors": [
+      { "code": "required", "instance_pointer": "", "schema_pointer": "" },
+      { "code": "type", "instance_pointer": "/amount", "schema_pointer": "/properties/amount" },
+      { "code": "boolean_schema", "instance_pointer": "/note", "schema_pointer": "/additionalProperties" }
+    ],
+    "truncated": false
+  }
+}
+```
+
+A `required` issue points at the object that lacks the member, not at the
+member: above it sits at `/input` and does not name `job_id`.
+
+The input `{ notes }`, where `notes` holds 32,769 characters and the input
+encodes to 32,781 bytes, is refused with:
+
+```json
+{
+  "code": "TASK_INPUT_TOO_LARGE",
+  "category": "validation",
+  "message": "The task input is too large. Shorten the request or split the work into more than one task.",
+  "pointers": ["/input"],
+  "details": { "measured_bytes": 32781, "allowed_bytes": 32768 }
+}
+```
+
+An assignee who is not a user in the tenant is refused with:
+
+```json
+{
+  "code": "TASK_ASSIGNEE_INVALID",
+  "category": "validation",
+  "message": "The task assignee is invalid.",
+  "pointers": ["/assigned_to_id"],
+  "details": {}
+}
+```
+
+Pointers name the members of the task service's command, not the SDK's
+arguments, so the assignee is `/assigned_to_id` rather than `assignedToId`. A
+refused `reply()` arrives the same way, with the service's own code in
+`details.code` and the same categories: after a `runtime` refusal, calling
+`reply()` again with the same arguments resends the kept message rather than
+posting it twice.
+
+### Space documents
+
+`simple.documents.stage()` stores a file without attaching it to any record and
+returns its handle. The host uploads it, so a large file never travels inside
+an action request. The file's bytes are transferred to the host, not copied.
+
+```typescript
+const picker = document.querySelector<HTMLInputElement>('#packet')!
+const { handle } = await simple.documents.stage({ file: picker.files![0] })
+
+// A plain Blob has no name of its own, so it needs one.
+await simple.documents.stage({
+  file: new Blob([csv]),
+  mimeType: 'text/csv',
+  name: 'quantities.csv',
+})
+```
+
+The handle is `{ file_hash, filename, mime_type, size, storage_path, scope? }`.
+`name` defaults to a `File`'s own name, and `mimeType` to the file's type, then
+to `application/octet-stream`. A staged document is not attached to anything
+yet; attach its handle through the workflow that owns the record.
+
 ---
 
 ## API Documentation

package/dist/ai.d.ts

@@ -65,6 +65,52 @@ export interface JSONSchemaArray extends JSONSchemaBase {
  * This provides developers with precise autocompletion and type-checking.
  */
 export type JSONSchema = JSONSchemaArray | JSONSchemaBoolean | JSONSchemaNumber | JSONSchemaObject | JSONSchemaString;
+/**
+ * A stored file handed to an AI operation, together with what should be done
+ * with it.
+ *
+ * A PDF travels to the model as a PDF, because the model reads one: its tables,
+ * its layout and its figures survive the trip, and none of them survive being
+ * turned into text. Asking for text is therefore opt-in.
+ *
+ * The page range and `deliver_as` are two questions, asked in that order. The
+ * range says WHICH DOCUMENT the call is about: those pages are taken out of
+ * the PDF first, and everything after that is about them and nothing else.
+ * `deliver_as` then says how that document should reach the model.
+ *
+ * Refused, before the file is read or anything is spent:
+ * - `first_page` or `last_page` on anything that is not a PDF;
+ * - one of the pair without the other, a `first_page` below 1, a `last_page`
+ *   before `first_page`, or either one not a whole number;
+ * - a range that runs past the end of the document;
+ * - `deliver_as: 'text'` on an image, which is not read as text;
+ * - `deliver_as: 'document'` on a Word, Excel, PowerPoint, CSV, RTF or text
+ *   file,
+ *   which only ever travels as text.
+ *
+ * A page the platform cannot read as text sends the pages asked for as a PDF
+ * instead, so an answer is never built on text with a hole in it.
+ *
+ * Pages asked for as text arrive numbered from 1, because by then they are a
+ * document of their own. A line above them says which pages of which document
+ * they were, rather than the numbers being rewritten inside the text: a page
+ * number printed in a header or a cross-reference cannot be told apart from a
+ * page label, so editing them would corrupt the document's own words.
+ */
+export type AIDocumentInput = DocumentHandle & {
+    /** The first page to use, counted from 1. Named with `last_page`. PDF only. */
+    first_page?: number;
+    /** The last page to use, included. Named with `first_page`. PDF only. */
+    last_page?: number;
+    /**
+     * How the document reaches the model: `'document'`, the default, sends the
+     * document itself; `'text'` sends the text the platform reads out of it.
+     *
+     * Both answers are sayable, so the default can be written down rather than
+     * left to the absence of a key.
+     */
+    deliver_as?: 'document' | 'text';
+};
 /**
  * A set of common configuration options shared across all AI operations.
  * This adheres to the DRY principle, ensuring a consistent API surface.
@@ -200,22 +246,26 @@ export interface AIExecutionResult {
  * Extracts structured data from a given input using the Simple AI engine.
  *
  * @param input The source data for the extraction (string, document handle, or object).
+ *   A document handle may carry `deliver_as`, `first_page` and `last_page`; see
+ *   `AIDocumentInput`.
  * @param options The configuration for the extraction operation.
  * @param context The execution context provided by the host.
  * @returns A promise that resolves to an `AIExecutionResult` object.
  * @throws Will throw an error if the operation fails or inputs are invalid.
  */
-export declare function extract(input: DocumentHandle | object | string, options: AIExtractOptions, context: Context): Promise<AIExecutionResult>;
+export declare function extract(input: AIDocumentInput | DocumentHandle | object | string, options: AIExtractOptions, context: Context): Promise<AIExecutionResult>;
 /**
  * Generates a summary for a given input using the Simple AI engine.
  *
  * @param input The source data for the summarization (string, document handle, or object).
+ *   A document handle may carry `deliver_as`, `first_page` and `last_page`; see
+ *   `AIDocumentInput`.
  * @param options The configuration for the summarization operation.
  * @param context The execution context provided by the host.
  * @returns A promise that resolves to an `AIExecutionResult` object containing the summary.
  * @throws Will throw an error if the operation fails or inputs are invalid.
  */
-export declare function summarize(input: DocumentHandle | object | string, options: AISummarizeOptions, context: Context): Promise<AIExecutionResult>;
+export declare function summarize(input: AIDocumentInput | DocumentHandle | object | string, options: AISummarizeOptions, context: Context): Promise<AIExecutionResult>;
 /**
  * Transcribes audio or video from a document handle using the Simple AI engine.
  *

package/dist/ai.js

@@ -5,8 +5,9 @@ import { execute as hostExecute } from './host';
 /**
  * Recursively processes an object to detect and upload pending files.
  * When a pending DocumentHandle is detected (has `pending: true` and `file_hash`),
- * it calls the ephemeral upload host function and replaces the pending handle
- * with the ephemeral handle returned from the upload.
+ * it calls the ephemeral upload host function and hands the operation the
+ * stored handle the upload answered with, carrying over the keys the caller
+ * put on the handle.
  *
  * @internal
  */
@@ -19,7 +20,23 @@ async function _uploadPendingFiles(obj, context) {
         if (!response.ok) {
             throw new Error(response.error?.message || 'Failed to upload pending file');
         }
-        return response.data;
+        // The upload answers with the stored file's own reference: where it is,
+        // what it hashes to, its name, its type and its size. Every one of those
+        // keys describes the file, so every one of them is taken from the upload
+        // and none is carried over — a value from before the upload would name a
+        // file that is no longer the one being read.
+        //
+        // Everything else on the handle is the caller's: how the file is to be
+        // sent, which of its pages, and any key added to a file reference later.
+        // Those describe the request, not the file, and the upload knows nothing
+        // about them, so they are carried over. A caller reads a pending file and
+        // a stored one the same way.
+        //
+        // `pending` is the one key that is neither: it said the bytes had not been
+        // stored yet. They have been now, so it is dropped. A handle that still
+        // called itself pending would be uploaded a second time on the next pass.
+        const { pending: _pending, ...caller } = obj;
+        return { ...caller, ...response.data };
     }
     if (Array.isArray(obj)) {
         return Promise.all(obj.map(item => _uploadPendingFiles(item, context)));
@@ -82,6 +99,8 @@ async function _executeAIOperation(operation, input, options, context) {
  * Extracts structured data from a given input using the Simple AI engine.
  *
  * @param input The source data for the extraction (string, document handle, or object).
+ *   A document handle may carry `deliver_as`, `first_page` and `last_page`; see
+ *   `AIDocumentInput`.
  * @param options The configuration for the extraction operation.
  * @param context The execution context provided by the host.
  * @returns A promise that resolves to an `AIExecutionResult` object.
@@ -105,6 +124,8 @@ export async function extract(input, options, context) {
  * Generates a summary for a given input using the Simple AI engine.
  *
  * @param input The source data for the summarization (string, document handle, or object).
+ *   A document handle may carry `deliver_as`, `first_page` and `last_page`; see
+ *   `AIDocumentInput`.
  * @param options The configuration for the summarization operation.
  * @param context The execution context provided by the host.
  * @returns A promise that resolves to an `AIExecutionResult` object containing the summary.

package/dist/space/core.d.ts

@@ -1,3 +1,4 @@
+import type { DocumentHandle } from '../types.js';
 export declare const PROTOCOL_VERSION: 1;
 export type SpaceContext = {
     applicationId: string;
@@ -29,6 +30,66 @@ export interface RecordSnapshot {
     values: Readonly<Record<string, unknown>>;
 }
 export type GraphQLVariables = Readonly<Record<string, unknown>>;
+/** A value that survives a JSON round trip unchanged. */
+export type JsonValue = boolean | JsonObject | null | number | string | readonly JsonValue[];
+/** A JSON object: not `null`, not an array, and not a single value. */
+export interface JsonObject {
+    readonly [key: string]: JsonValue;
+}
+/** The platform-standard status of a task. */
+export type TaskStatus = 'cancelled' | 'completed' | 'failed' | 'in_progress' | 'queued' | 'waiting';
+export interface TaskCreateInput {
+    /** The user the task is assigned to. Omit it to assign the task to its creator. */
+    assignedToId?: string;
+    /**
+     * The typed input the task type declares for its tasks. It is always a JSON
+     * object, even when the task type needs nothing: then it is `{}`.
+     */
+    input: JsonObject;
+    /** The ID of the task type the task is created from. */
+    taskTypeId: string;
+    title: string;
+}
+export interface TaskCreateResult {
+    task: {
+        id: string;
+        revision: number;
+        status: TaskStatus;
+    };
+}
+export interface TaskReplyInput {
+    content: string;
+    /** The message this reply answers, when it answers one. */
+    inReplyToMessageId?: string;
+    taskId: string;
+}
+export interface TaskReplyResult {
+    messageId: string;
+    /** The task's revision after the reply was recorded. */
+    taskRevision: number;
+}
+export interface SimpleTasksClient {
+    create: (task: TaskCreateInput) => Promise<TaskCreateResult>;
+    reply: (reply: TaskReplyInput) => Promise<TaskReplyResult>;
+}
+/** A stored file that is not yet attached to any record. */
+export interface StagedDocumentHandle extends DocumentHandle {
+    scope?: 'ephemeral' | 'record' | 'staged';
+}
+export interface DocumentStageInput {
+    /** The file to stage. Its bytes are transferred to the host, not copied. */
+    file: Blob | File;
+    /** Defaults to the file's own type, then to `application/octet-stream`. */
+    mimeType?: string;
+    /** Defaults to the name of a `File`. A plain `Blob` has none, so it needs one. */
+    name?: string;
+}
+export interface DocumentStageResult {
+    handle: StagedDocumentHandle;
+}
+export interface SimpleDocumentsClient {
+    stage: (document: DocumentStageInput) => Promise<DocumentStageResult>;
+}
 export interface SpaceDataTransport {
     execute: <TResult = unknown>(document: string, variables?: GraphQLVariables) => Promise<TResult>;
 }
@@ -45,9 +106,11 @@ export interface RecordHandle {
 export interface SimpleClient {
     context: SpaceContext;
     data: SimpleDataClient;
+    documents: SimpleDocumentsClient;
     records: {
         current: () => Promise<RecordHandle>;
     };
+    tasks: SimpleTasksClient;
 }
 export interface SpaceProtocolErrorPayload {
     code: string;
@@ -104,7 +167,30 @@ export interface RecordSubmitResult {
     ok: boolean;
     snapshot: RecordSnapshot;
 }
-export type ProtocolRequest = CurrentRecordRequest | RecordSubmitRequest | RecordUpdateRequest;
+export interface TaskCreateRequest {
+    operation: 'task.create';
+    payload: TaskCreateInput;
+    protocol: typeof PROTOCOL_VERSION;
+    requestId: string;
+}
+export interface TaskReplyRequest {
+    operation: 'task.reply';
+    payload: TaskReplyInput;
+    protocol: typeof PROTOCOL_VERSION;
+    requestId: string;
+}
+export interface DocumentStageRequest {
+    operation: 'document.stage';
+    payload: {
+        /** Transferred with the request, so it is detached in the Space afterwards. */
+        bytes: ArrayBuffer;
+        mimeType: string;
+        name: string;
+    };
+    protocol: typeof PROTOCOL_VERSION;
+    requestId: string;
+}
+export type ProtocolRequest = CurrentRecordRequest | DocumentStageRequest | RecordSubmitRequest | RecordUpdateRequest | TaskCreateRequest | TaskReplyRequest;
 export interface ProtocolSuccessResponse<TResult> {
     ok: true;
     protocol: typeof PROTOCOL_VERSION;
@@ -119,12 +205,22 @@ export interface ProtocolErrorResponse {
 }
 export type ProtocolResponse<TResult> = ProtocolErrorResponse | ProtocolSuccessResponse<TResult>;
 export interface SpaceTransport {
-    request: <TResult>(request: ProtocolRequest) => Promise<ProtocolResponse<TResult>>;
+    /**
+     * `transfer` names buffers inside the request whose ownership moves to the
+     * host with it instead of being copied. A transport that cannot transfer
+     * sends them by value.
+     */
+    request: <TResult>(request: ProtocolRequest, transfer?: ArrayBuffer[]) => Promise<ProtocolResponse<TResult>>;
 }
 export interface SimpleClientOptions {
     context?: SpaceContext;
     dataTransport?: SpaceDataTransport;
+    /** Present only when the host negotiated the document protocol. */
+    documentTransport?: SpaceTransport;
     nextRequestId?: () => string;
+    /** Present only when the host negotiated the task protocol. */
+    taskTransport?: SpaceTransport;
+    /** Present only when the host negotiated the record protocol. */
     transport?: SpaceTransport;
 }
 /**
@@ -134,5 +230,5 @@ export interface SimpleClientOptions {
  * contract can be exercised in a first-party direct adapter and in any UI
  * framework without importing browser-specific code.
  */
-export declare function createSimpleClient({ context, dataTransport, nextRequestId, transport, }: SimpleClientOptions): SimpleClient;
+export declare function createSimpleClient({ context, dataTransport, documentTransport, nextRequestId, taskTransport, transport, }: SimpleClientOptions): SimpleClient;
 export declare function isSpaceContext(value: unknown): value is SpaceContext;

package/dist/space/core.js

@@ -34,7 +34,7 @@ export class SpaceDataError extends Error {
  * contract can be exercised in a first-party direct adapter and in any UI
  * framework without importing browser-specific code.
  */
-export function createSimpleClient({ context = { kind: 'standalone' }, dataTransport, nextRequestId = createRequestId, transport, }) {
+export function createSimpleClient({ context = { kind: 'standalone' }, dataTransport, documentTransport, nextRequestId = createRequestId, taskTransport, transport, }) {
     const immutableContext = immutableSpaceContext(context);
     return {
         context: immutableContext,
@@ -42,6 +42,7 @@ export function createSimpleClient({ context = { kind: 'standalone' }, dataTrans
             mutate: (document, variables) => executeData(dataTransport, document, variables),
             query: (document, variables) => executeData(dataTransport, document, variables),
         },
+        documents: createDocumentsClient(documentTransport, nextRequestId),
         records: {
             async current() {
                 if (immutableContext.kind !== 'record') {
@@ -70,6 +71,7 @@ export function createSimpleClient({ context = { kind: 'standalone' }, dataTrans
                 return new ProtocolRecordHandle(result, nextRequestId, transport);
             },
         },
+        tasks: createTasksClient(taskTransport, nextRequestId),
     };
 }
 export function isSpaceContext(value) {
@@ -97,6 +99,83 @@ function executeData(dataTransport, document, variables) {
     }
     return dataTransport.execute(document, variables);
 }
+/**
+ * A staged document is stored without being attached to a record, so staging
+ * is available in any Space whose host negotiated the document protocol.
+ */
+function createDocumentsClient(transport, nextRequestId) {
+    return {
+        async stage(document) {
+            if (!transport) {
+                throw new SpaceProtocolError({
+                    code: 'unavailable',
+                    message: 'Documents are unavailable because the Space host did not negotiate the document protocol.',
+                });
+            }
+            const { file, mimeType, name } = readDocumentStageInput(document);
+            // A Blob cannot itself be transferred. Its bytes are read into a buffer
+            // once, and that buffer is handed to the host rather than copied again.
+            const bytes = await file.arrayBuffer();
+            const request = {
+                operation: 'document.stage',
+                payload: { bytes, mimeType, name },
+                protocol: PROTOCOL_VERSION,
+                requestId: nextRequestId(),
+            };
+            const response = await transport.request(request, [bytes]);
+            const result = readResponse(response, request);
+            if (!isDocumentStageResult(result))
+                throw invalidResponse('The document-stage response is malformed.');
+            return { handle: { ...result.handle } };
+        },
+    };
+}
+/**
+ * Tasks are not tied to a page record, so they are available in any Space
+ * whose host negotiated the task protocol, standalone or record.
+ */
+function createTasksClient(transport, nextRequestId) {
+    const requireTransport = () => {
+        if (!transport) {
+            throw new SpaceProtocolError({
+                code: 'unavailable',
+                message: 'Tasks are unavailable because the Space host did not negotiate the task protocol.',
+            });
+        }
+        return transport;
+    };
+    return {
+        async create(task) {
+            const taskTransport = requireTransport();
+            const request = {
+                operation: 'task.create',
+                payload: readTaskCreatePayload(task),
+                protocol: PROTOCOL_VERSION,
+                requestId: nextRequestId(),
+            };
+            const response = await taskTransport.request(request);
+            const result = readResponse(response, request);
+            if (!isTaskCreateResult(result))
+                throw invalidResponse('The task-create response is malformed.');
+            const { id, revision, status } = result.task;
+            return { task: { id, revision, status } };
+        },
+        async reply(reply) {
+            const taskTransport = requireTransport();
+            const request = {
+                operation: 'task.reply',
+                payload: readTaskReplyPayload(reply),
+                protocol: PROTOCOL_VERSION,
+                requestId: nextRequestId(),
+            };
+            const response = await taskTransport.request(request);
+            const result = readResponse(response, request);
+            if (!isTaskReplyResult(result))
+                throw invalidResponse('The task-reply response is malformed.');
+            return { messageId: result.messageId, taskRevision: result.taskRevision };
+        },
+    };
+}
 class ProtocolRecordHandle {
     constructor({ sessionId, snapshot }, nextRequestId, transport) {
         _ProtocolRecordHandle_nextRequestId.set(this, void 0);
@@ -168,6 +247,137 @@ function deepFreeze(value) {
 function invalidResponse(message) {
     return new SpaceProtocolError({ code: 'invalid_response', message });
 }
+function invalidRequest(message) {
+    return new SpaceProtocolError({ code: 'invalid_request', message });
+}
+/**
+ * Checks a task before it is sent, so a plain-JavaScript caller learns what is
+ * wrong without a host round trip. The payload names only the members the
+ * operation defines; an optional member left out is not sent at all.
+ */
+function readTaskCreatePayload(task) {
+    if (!isObjectRecord(task))
+        throw invalidRequest('A task needs a title, a task type, and its input.');
+    if (!isNonBlankString(task.title))
+        throw invalidRequest('A task needs a title.');
+    if (!isNonBlankString(task.taskTypeId))
+        throw invalidRequest('A task needs the ID of its task type.');
+    if (!isJsonObject(task.input))
+        throw invalidRequest('A task input must be a JSON object, and everything in it a JSON value.');
+    if (task.assignedToId !== undefined && !isNonBlankString(task.assignedToId))
+        throw invalidRequest('A task assignee must be a user ID.');
+    return {
+        ...(task.assignedToId === undefined ? {} : { assignedToId: task.assignedToId }),
+        input: task.input,
+        taskTypeId: task.taskTypeId,
+        title: task.title,
+    };
+}
+function readTaskReplyPayload(reply) {
+    if (!isObjectRecord(reply))
+        throw invalidRequest('A task reply needs a task ID and its content.');
+    if (!isNonBlankString(reply.taskId))
+        throw invalidRequest('A task reply needs the ID of its task.');
+    if (!isNonBlankString(reply.content))
+        throw invalidRequest('A task reply needs content.');
+    if (reply.inReplyToMessageId !== undefined && !isNonBlankString(reply.inReplyToMessageId))
+        throw invalidRequest('A task reply can answer only a message ID.');
+    return {
+        content: reply.content,
+        ...(reply.inReplyToMessageId === undefined ? {} : { inReplyToMessageId: reply.inReplyToMessageId }),
+        taskId: reply.taskId,
+    };
+}
+/**
+ * The task.create contract takes an object for input, never null, an array, or
+ * a single value, so a caller learns that here instead of from the host.
+ */
+function isJsonObject(value) {
+    return isObjectRecord(value) && isJsonValue(value);
+}
+/**
+ * Accepts only what JSON carries unchanged. A structured clone would pass a
+ * Date, Map, or class instance through a MessagePort and a JSON transport
+ * would not, so the task input is held to JSON on every transport.
+ */
+function isJsonValue(value, ancestors = new Set()) {
+    if (value === null || typeof value === 'boolean' || typeof value === 'string')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (!value || typeof value !== 'object' || ancestors.has(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null)
+        return false;
+    ancestors.add(value);
+    const valid = Object.values(value).every(child => isJsonValue(child, ancestors));
+    ancestors.delete(value);
+    return valid;
+}
+function readDocumentStageInput(document) {
+    if (!isObjectRecord(document) || !isBlob(document.file))
+        throw invalidRequest('A staged document needs a File or Blob.');
+    const name = document.name ?? readFileName(document.file);
+    if (!isNonBlankString(name))
+        throw invalidRequest('A staged document needs a name, and a Blob has none of its own.');
+    if (document.mimeType !== undefined && typeof document.mimeType !== 'string')
+        throw invalidRequest('A staged document type must be a MIME type.');
+    return {
+        file: document.file,
+        mimeType: document.mimeType || document.file.type || 'application/octet-stream',
+        name,
+    };
+}
+/** Duck-typed so a Blob from another realm, or a test double, is accepted. */
+function isBlob(value) {
+    if (!isObjectRecord(value))
+        return false;
+    return typeof value.arrayBuffer === 'function' && typeof value.size === 'number' && typeof value.type === 'string';
+}
+function readFileName(file) {
+    const { name } = file;
+    return typeof name === 'string' ? name : undefined;
+}
+function isNonBlankString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function isNonNegativeInteger(value) {
+    return Number.isSafeInteger(value) && value >= 0;
+}
+const DOCUMENT_SCOPES = new Set([
+    'ephemeral',
+    'record',
+    'staged',
+]);
+function isDocumentStageResult(value) {
+    if (!isObjectRecord(value) || !isObjectRecord(value.handle))
+        return false;
+    const handle = value.handle;
+    return isNonBlankString(handle.file_hash)
+        && isNonBlankString(handle.filename)
+        && typeof handle.mime_type === 'string'
+        && isNonNegativeInteger(handle.size)
+        && isNonBlankString(handle.storage_path)
+        && (handle.scope === undefined || DOCUMENT_SCOPES.has(handle.scope));
+}
+const TASK_STATUSES = new Set([
+    'cancelled',
+    'completed',
+    'failed',
+    'in_progress',
+    'queued',
+    'waiting',
+]);
+function isTaskCreateResult(value) {
+    if (!isObjectRecord(value) || !isObjectRecord(value.task))
+        return false;
+    const { id, revision, status } = value.task;
+    return isNonBlankString(id) && isNonNegativeInteger(revision) && TASK_STATUSES.has(status);
+}
+function isTaskReplyResult(value) {
+    return isObjectRecord(value) && isNonBlankString(value.messageId) && isNonNegativeInteger(value.taskRevision);
+}
 function isCurrentRecordResult(value) {
     if (!value || typeof value !== 'object')
         return false;

package/dist/space/index.d.ts

@@ -1,12 +1,12 @@
 import type { SimpleClient } from './core.js';
 import { SpaceDataError, SpaceProtocolError } from './core.js';
 export { SpaceDataError, SpaceProtocolError, };
-export type { GraphQLVariables, RecordErrorSnapshot, RecordFieldSnapshot, RecordFormError, RecordHandle, RecordSnapshot, RecordSubmitResult, RecordUpdateResult, SimpleClient, SimpleDataClient, SpaceContext, SpaceDataErrorPayload, SpaceProtocolErrorPayload, } from './core.js';
+export type { DocumentStageInput, DocumentStageResult, GraphQLVariables, JsonObject, JsonValue, RecordErrorSnapshot, RecordFieldSnapshot, RecordFormError, RecordHandle, RecordSnapshot, RecordSubmitResult, RecordUpdateResult, SimpleClient, SimpleDataClient, SimpleDocumentsClient, SimpleTasksClient, SpaceContext, SpaceDataErrorPayload, SpaceProtocolErrorPayload, StagedDocumentHandle, TaskCreateInput, TaskCreateResult, TaskReplyInput, TaskReplyResult, TaskStatus, } from './core.js';
 interface MessagePortLike {
     onmessage: null | ((event: {
         data: unknown;
     }) => void);
-    postMessage: (message: unknown) => void;
+    postMessage: (message: unknown, transfer?: ArrayBuffer[]) => void;
     start?: () => void;
 }
 export interface SpaceWindowLike {
@@ -27,7 +27,8 @@ export interface ConnectSpaceOptions {
 }
 /**
  * Connects any embedded Space to its parent through the dedicated MessagePort
- * handshake. Record operations become available only when the host negotiates
- * record protocol v1 for a configured record view.
+ * handshake. Each protocol capability is offered in `SPACE_READY` and becomes
+ * available only when the host negotiates it in `INIT_RPC`: record operations
+ * for a configured record view, and task and document operations in any Space.
  */
 export declare function connectSpace({ targetOrigin, window }: ConnectSpaceOptions): Promise<SimpleClient>;

package/dist/space/index.js

@@ -2,8 +2,9 @@ import { createSimpleClient, isSpaceContext, PROTOCOL_VERSION, SpaceDataError, S
 export { SpaceDataError, SpaceProtocolError, };
 /**
  * Connects any embedded Space to its parent through the dedicated MessagePort
- * handshake. Record operations become available only when the host negotiates
- * record protocol v1 for a configured record view.
+ * handshake. Each protocol capability is offered in `SPACE_READY` and becomes
+ * available only when the host negotiates it in `INIT_RPC`: record operations
+ * for a configured record view, and task and document operations in any Space.
  */
 export function connectSpace({ targetOrigin, window = globalThis.window }) {
     if (!window) {
@@ -33,18 +34,22 @@ export function connectSpace({ targetOrigin, window = globalThis.window }) {
                 return;
             }
             const transport = createMessagePortTransport(port);
-            const recordTransport = event.data.protocols?.record === PROTOCOL_VERSION
-                ? transport
-                : undefined;
+            const protocols = event.data.protocols;
             resolve(createSimpleClient({
                 context: event.data.context,
                 dataTransport: transport,
-                transport: recordTransport,
+                documentTransport: protocols?.document === PROTOCOL_VERSION ? transport : undefined,
+                taskTransport: protocols?.task === PROTOCOL_VERSION ? transport : undefined,
+                transport: protocols?.record === PROTOCOL_VERSION ? transport : undefined,
             }));
         };
         window.addEventListener('message', onMessage);
         window.parent.postMessage({
-            protocols: { record: [PROTOCOL_VERSION] },
+            protocols: {
+                document: [PROTOCOL_VERSION],
+                record: [PROTOCOL_VERSION],
+                task: [PROTOCOL_VERSION],
+            },
             type: 'SPACE_READY',
         }, targetOrigin);
     });
@@ -94,12 +99,12 @@ function createMessagePortTransport(port) {
                 });
             });
         },
-        request: (request) => {
+        request: (request, transfer = []) => {
             return new Promise((resolve) => {
                 pending.set(request.requestId, {
                     resolve: response => resolve(response),
                 });
-                port.postMessage({ request, type: 'SPACE_PROTOCOL_REQUEST' });
+                port.postMessage({ request, type: 'SPACE_PROTOCOL_REQUEST' }, transfer);
             });
         },
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simpleplatform/sdk",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "Simple Platform Typescript SDK",
   "license": "Apache-2.0",
   "homepage": "https://docs.simple.dev",