@simpleplatform/sdk 2.2.0 → 2.4.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
@@ -209,6 +382,60 @@ console.log(result.data.summary) // "Customer called regarding..."
 console.log(result.data.participants) // ["Customer", "Support Agent"]
 ```
 
+#### Transcribe PDF Pages
+
+Read the pages of a PDF that have no usable text of their own — scans,
+image-only exhibits — from their images. Each such page is transcribed once,
+and it is the same transcription an `extract` or `summarize` that asks for text
+is given in the page's place, so a quote on an image page can be checked
+against the text the answer was built on. Pages with a readable text layer are
+not returned.
+
+```typescript
+import { transcribePages } from '@simpleplatform/sdk/ai'
+
+const { data } = await transcribePages(
+  { ...contract, first_page: 40, last_page: 52 },
+  {},
+  request.context
+)
+
+for (const page of data.pages) {
+  if ('error' in page) {
+    console.log(`page ${page.page} could not be read: ${page.error}`)
+    continue
+  }
+
+  console.log(page.page, page.text.includes(quote))
+}
+```
+
+Pages are numbered in the original document. Transcriptions are kept per
+version of the file and page, so a page already read for an `extract` or
+`summarize` that asked for text (`deliver_as: 'text'`) is not read again.
+
+A page is not transcribed twice to check itself: that would be the same model
+reading the same image again, doubling the cost of every scanned page without
+adding independence. To check an answer independently, read the pages a second
+way — as the document itself (`deliver_as: 'document'`) — and compare.
+
+#### How Files Travelled
+
+Every AI result says how each file it carried reached the model, in
+`metadata.delivery`: `deliveredAs` (`'document'`, `'text'` or `'image'`), the
+range it was cut to, the pages transcribed from their images, and — when text
+was asked for and the document was sent instead — a `fallback` naming the pages
+that could not be read and why.
+
+```typescript
+const result = await extract({ ...contract, deliver_as: 'text' }, { prompt, schema }, request.context)
+
+for (const file of result.metadata.delivery ?? []) {
+  if (file.fallback)
+    console.log(`${file.filename} was read as a PDF: ${file.fallback.message}`)
+}
+```
+
 ### GraphQL Module
 
 Execute type-safe database operations with GraphQL:

package/dist/ai.d.ts

@@ -88,8 +88,12 @@ export type JSONSchema = JSONSchemaArray | JSONSchemaBoolean | JSONSchemaNumber
  *   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.
+ * A page with no usable text of its own — a scan, or text that reads as noise
+ * — is read from its image instead, and that text stands in its place, marked
+ * `[Transcribed from the page image.]` under its page label. Only if that
+ * reading fails are the pages asked for sent as a PDF, so an answer is never
+ * built on text with a hole in it. The answer's `metadata.delivery` says which
+ * happened.
  *
  * 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
@@ -203,6 +207,62 @@ export interface AITranscribeOptions extends Omit<AICommonOptions, 'prompt'> {
      */
     summarize?: boolean;
 }
+/**
+ * A PDF whose pages are to be transcribed, and optionally which of them.
+ *
+ * `first_page` and `last_page` work as they do for any AI operation: counted
+ * from 1, both ends included, named together or not at all, and cut out first.
+ * `deliver_as` has no meaning here, because the pages are answered as text.
+ */
+export type AITranscribePagesInput = DocumentHandle & Omit<AIDocumentInput, 'deliver_as' | keyof DocumentHandle>;
+/**
+ * Configuration options for `transcribePages`. There is no prompt and no
+ * reasoning switch: the instructions are the platform's, and every page is
+ * read at the platform's own accuracy-first effort.
+ */
+export interface AITranscribePagesOptions {
+    /**
+     * If true, runs the operation again rather than serving its kept answer.
+     * A page already read is still served from its kept read, which is tied to
+     * this version of the file and to the platform's instructions.
+     */
+    regenerate?: boolean;
+    /** (Optional) The maximum time in milliseconds to wait for the operation. */
+    timeout?: number;
+}
+/**
+ * One page's transcription, or why it has none. Pages are numbered in the
+ * original document.
+ */
+export type AIPageTranscription = {
+    /** Why the page could not be read. No partial text is given. */
+    error: string;
+    /** The page's number in the original document. */
+    page: number;
+} | {
+    /** The page's number in the original document. */
+    page: number;
+    /**
+     * The page's text as read from its image: verbatim markdown, in reading
+     * order, tables as markdown tables, `[illegible]` where a word could not
+     * be read. An empty string is a read that found the page blank.
+     */
+    text: string;
+};
+/**
+ * The response of `transcribePages`.
+ */
+export interface AITranscriptionResult {
+    /** Every page of the document, or of the range, that has no usable text layer. */
+    data: {
+        pages: AIPageTranscription[];
+    };
+    /**
+     * The operation's metadata. Its token counts are zero: each page read is
+     * charged where it was made, once, whichever operation asked for it.
+     */
+    metadata: AIExecutionResult['metadata'];
+}
 /**
  * Options for searching faces within the Face Engine.
  */
@@ -218,6 +278,34 @@ export interface AIFaceSearchOptions {
      */
     similarityThreshold?: number;
 }
+/**
+ * How one file an AI operation carried reached the model. Page numbers are
+ * the original document's, whatever range was cut from it.
+ */
+export interface AIFileDelivery {
+    /** How the file travelled: as the document itself, as its text, or as an image. */
+    deliveredAs: 'document' | 'image' | 'text';
+    /**
+     * Present only when text was asked for and the document was sent instead:
+     * the pages whose images could not be read, and why.
+     */
+    fallback?: {
+        /** What went wrong, page by page, in the platform's words. */
+        message: string;
+        /** The pages that could not be transcribed. */
+        pages: number[];
+        /** Why the document travelled instead of its text. */
+        reason: 'transcription_failed';
+    };
+    /** The file's name. */
+    filename: string;
+    /** The first page of the range the file was cut to, when one was named. */
+    firstPage?: number;
+    /** The last page of the range the file was cut to, when one was named. */
+    lastPage?: number;
+    /** The pages whose text was read from their images rather than their text layer. */
+    transcribedPages: number[];
+}
 /**
  * The response structure from a successful AI `extract` or `summarize` operation.
  */
@@ -232,6 +320,12 @@ export interface AIExecutionResult {
      * providing context to the user.
      */
     metadata: {
+        /**
+         * How each file the operation carried reached the model, in input order.
+         * Absent when the operation carried no file, and on an answer kept from
+         * before the platform reported it.
+         */
+        delivery?: AIFileDelivery[];
         /** The number of tokens in the input prompt. */
         inputTokens: number;
         /** The number of tokens in the generated output. */
@@ -301,6 +395,48 @@ export declare function summarize(input: AIDocumentInput | DocumentHandle | obje
  * // Returns: { language: "en", summary: "...", participants: ["Participant 1", "Participant 2"] }
  */
 export declare function transcribe(input: DocumentHandle, options: AITranscribeOptions, context: Context): Promise<AIExecutionResult>;
+/**
+ * Transcribes the pages of a PDF that have no usable text of their own — scans,
+ * image-only exhibits, text that reads as noise — from their images.
+ *
+ * Every such page is read once, and it is the same transcription an `extract`
+ * or `summarize` that asked for text is given in the page's place, so a caller
+ * can check that a quote on an image page is really there by looking for it in
+ * the text the answer was built on. Pages the platform reads as text are
+ * neither read nor returned.
+ *
+ * A page is not transcribed a second time to check the first: that would be
+ * the same model reading the same image again, doubling the cost of every
+ * scanned page without being independent of the first read. An independent
+ * check reads the pages a second way — as the document itself
+ * (`deliver_as: 'document'`) — and compares the answers.
+ *
+ * Transcriptions are kept per version of the file and page, and shared with
+ * every other AI operation: a page already read for an `extract` or
+ * `summarize` that asked for text is not read again.
+ *
+ * @param document The PDF, as a DocumentHandle. Add `first_page` and
+ *   `last_page` to transcribe only those pages; they are counted from 1 and
+ *   the answer numbers pages in the original document.
+ * @param options Optional `regenerate` and `timeout`.
+ * @param context The execution context provided by the host.
+ * @returns A promise that resolves to each page's transcription, or why it has none.
+ * @throws Will throw an error if the operation fails or the input is not a PDF.
+ *
+ * @example
+ * const { data } = await transcribePages(
+ *   { ...contract, first_page: 40, last_page: 52 },
+ *   {},
+ *   context,
+ * )
+ *
+ * for (const page of data.pages) {
+ *   if ('error' in page)
+ *     continue
+ *   const quoted = page.text.includes(quote)
+ * }
+ */
+export declare function transcribePages(document: AITranscribePagesInput, options: AITranscribePagesOptions, context: Context): Promise<AITranscriptionResult>;
 /**
  * Enrolls a face for a subject. The face is associated with the given `subjectId`
  * within the tenant's secure collection.

package/dist/ai.js

@@ -85,6 +85,7 @@ async function _executeAIOperation(operation, input, options, context) {
     return {
         data,
         metadata: {
+            ...(Array.isArray(metadata.delivery) && { delivery: metadata.delivery.map(_fileDelivery) }),
             inputTokens: metadata.input_tokens,
             outputTokens: metadata.output_tokens,
             reasoning: metadata.reasoning,
@@ -92,6 +93,38 @@ async function _executeAIOperation(operation, input, options, context) {
         },
     };
 }
+/**
+ * One file's delivery as the platform reports it, in the SDK's own casing.
+ * A key the platform sends as `null` is left out rather than carried as one.
+ *
+ * @internal
+ */
+function _fileDelivery(file) {
+    return {
+        deliveredAs: file.delivered_as,
+        ...(file.fallback && { fallback: file.fallback }),
+        filename: file.filename,
+        ...(typeof file.first_page === 'number' && { firstPage: file.first_page }),
+        ...(typeof file.last_page === 'number' && { lastPage: file.last_page }),
+        transcribedPages: Array.isArray(file.transcribed_pages) ? file.transcribed_pages : [],
+    };
+}
+/**
+ * One page's transcription as the platform reports it: its text or its error,
+ * never both. An error wins, so no partial text is handed on, and a page that
+ * carries no text is reported as unread rather than as text that is not there.
+ *
+ * @internal
+ */
+function _pageTranscription(page) {
+    if (typeof page.text === 'string' && typeof page.error !== 'string') {
+        return { page: page.page, text: page.text };
+    }
+    return {
+        error: typeof page.error === 'string' ? page.error : 'no transcription was returned for this page',
+        page: page.page,
+    };
+}
 // ============================================================================
 // Public SDK Functions
 // ============================================================================
@@ -284,6 +317,61 @@ export async function transcribe(input, options, context) {
         schema,
     }, context);
 }
+/**
+ * Transcribes the pages of a PDF that have no usable text of their own — scans,
+ * image-only exhibits, text that reads as noise — from their images.
+ *
+ * Every such page is read once, and it is the same transcription an `extract`
+ * or `summarize` that asked for text is given in the page's place, so a caller
+ * can check that a quote on an image page is really there by looking for it in
+ * the text the answer was built on. Pages the platform reads as text are
+ * neither read nor returned.
+ *
+ * A page is not transcribed a second time to check the first: that would be
+ * the same model reading the same image again, doubling the cost of every
+ * scanned page without being independent of the first read. An independent
+ * check reads the pages a second way — as the document itself
+ * (`deliver_as: 'document'`) — and compares the answers.
+ *
+ * Transcriptions are kept per version of the file and page, and shared with
+ * every other AI operation: a page already read for an `extract` or
+ * `summarize` that asked for text is not read again.
+ *
+ * @param document The PDF, as a DocumentHandle. Add `first_page` and
+ *   `last_page` to transcribe only those pages; they are counted from 1 and
+ *   the answer numbers pages in the original document.
+ * @param options Optional `regenerate` and `timeout`.
+ * @param context The execution context provided by the host.
+ * @returns A promise that resolves to each page's transcription, or why it has none.
+ * @throws Will throw an error if the operation fails or the input is not a PDF.
+ *
+ * @example
+ * const { data } = await transcribePages(
+ *   { ...contract, first_page: 40, last_page: 52 },
+ *   {},
+ *   context,
+ * )
+ *
+ * for (const page of data.pages) {
+ *   if ('error' in page)
+ *     continue
+ *   const quoted = page.text.includes(quote)
+ * }
+ */
+export async function transcribePages(document, options, context) {
+    if (!document || typeof document !== 'object' || !document.file_hash) {
+        throw new Error('The `document` parameter must be a valid DocumentHandle for `transcribePages`.');
+    }
+    const mimeType = (document.mime_type || '').split(';')[0].trim().toLowerCase();
+    if (mimeType !== 'application/pdf') {
+        throw new Error('`transcribePages` reads the pages of a PDF.');
+    }
+    const result = await _executeAIOperation('transcribe', document, options, context);
+    return {
+        data: { pages: Array.isArray(result.data?.pages) ? result.data.pages.map(_pageTranscription) : [] },
+        metadata: result.metadata,
+    };
+}
 // ============================================================================
 // Face Recognition API
 // ============================================================================

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.2.0",
+  "version": "2.4.0",
   "description": "Simple Platform Typescript SDK",
   "license": "Apache-2.0",
   "homepage": "https://docs.simple.dev",