@sprigr/apps-app-sdk 0.10.1 → 0.12.0

package/README.md

@@ -15,6 +15,7 @@ The runtime injects the `env.SPRIGR` host object **only on `/__sprigr/*` dispatc
 - `canEmit(env)` — whether an emit could reach the platform by either transport. Gate work that only exists to feed an emit on this, not on `env.SPRIGR?.emit`.
 - `withSprigrEmitFallback(env)` — repair `env.SPRIGR.emit` once and leave existing call sites untouched. Matches the host object's contract (resolves `{ ok, eventId, queued }`, throws on non-2xx).
 - `logToPlatform(env, entry | entry[], opts?)`: durable app logging from either context (`env.SPRIGR.log` on dispatch, `POST ${SPRIGR_PLATFORM_BASE}/internal/wfp/log` from an inline route). Rows land in the platform's `system_logs` Analytics Engine dataset (90-day retention, scoped to the install's company, category prefixed with the app slug), so use it instead of a per-webhook or per-tick audit row in your D1: D1 bills every row written, AE does not. Validation throws synchronously on a cap violation (summary 256, detail 4096, metadata JSON 3840, category 64 matching `[A-Za-z0-9._:-]`, 50 entries per call; nothing is ever truncated); after that the promise never rejects and resolves `{ ok: true, written }` or `{ ok: false, error, status?, detail? }`. Pass `{ waitUntil: ctx.waitUntil.bind(ctx) }` on an inline route so the send outlives the response. `withSprigrLogFallback(env, opts?)` installs `env.SPRIGR.log` once for many call sites; `canLog(env)` gates work whose only purpose is a log row; the `SprigrLogEntry` / `SprigrLogFn` types let your env interface declare the host member.
+- `partialUpdateData(env, objects, opts?)`: merge fields into objects already in the app's data index without reading them first (`env.SPRIGR.data.partialUpdate` on dispatch, `POST ${SPRIGR_PLATFORM_BASE}/internal/wfp/data/partial-update` from an inline route). Deep merge: nested objects recurse, arrays and scalars replace wholesale, absent keys survive, `null` overwrites. `createIfNotExists` defaults to `false`; on a sharded logical index every patch must carry the `shard_field` value or the batch fails with `shard_field_invalid`; 1000 objects per call like `import`. Throws on a bad batch before sending (`SprigrDataValidationError`) and on a platform rejection (`.status`, `.error`, `.detail` on the `Error`), the same contract as `import`. `canPartialUpdate(env)` gates a patch step on either transport; the `SprigrDataPartialUpdateOpts` / `SprigrDataPartialUpdateResult` types let your env interface declare the host member.
 - `resolveInstallBridge(env)` / `installTokenPost(bridge, path, body, opts?)`: build your own `/internal/wfp/*` fallback (collections, files, inbox) with the auth and error extraction handled. A non-2xx throws an `Error` whose `.status`, `.error` (the platform's code) and `.detail` are set alongside the message.
 - `overlaySprigr(env, sprigr)` — overlay a patched `SPRIGR` via `Object.create`. Never rebuild a dispatch-path env by spread: the real bindings live on the prototype and `SPRIGR` is non-enumerable, so `{ ...env }` yields an env whose `DB` is `undefined`.
 

package/dist/index.d.ts

@@ -649,6 +649,120 @@ declare function logToPlatform(env: WfpBridgeEnv, input: SprigrLogEntry | Sprigr
  */
 declare function withSprigrLogFallback<E extends WfpBridgeEnv & object>(env: E, opts?: LogToPlatformOptions): E;
 
+/**
+ * `env.SPRIGR.data.partialUpdate` from BOTH execution contexts.
+ *
+ * The platform exposes `env.SPRIGR.data.partialUpdate(objects, opts)` on
+ * every `/__sprigr/*` dispatch path, backed by
+ * `POST /internal/wfp/data/partial-update` on the provisioning worker. It
+ * merges fields into objects the app already imported without the app
+ * reading them first, which is what turns a read-then-`import` round trip
+ * (two platform calls, a race window, and a whole-object rewrite) into one
+ * call that touches only the fields named.
+ *
+ * Merge semantics, identical on both transports because the platform does
+ * the merge: nested objects recurse, arrays and scalars replace wholesale,
+ * keys the patch does not carry survive, and `null` is a value that
+ * overwrites. `createIfNotExists` defaults to `false` so a patch never
+ * creates half an object unless asked. On a hash- or date-sharded logical
+ * index every patch MUST carry the `shard_field` value or the whole batch
+ * fails with `shard_field_invalid`: a patch cannot be routed to its shard
+ * otherwise. The per-call cap is the same 1000 objects as `import`.
+ *
+ * This module carries two things:
+ *
+ *   1. `buildPartialUpdateBody`, the wire body both transports send, with
+ *      the client-side checks that reject a batch BEFORE anything is sent
+ *      (too many objects, a patch without a string `objectID`).
+ *   2. The inline-route fallback (`partialUpdateData`, `canPartialUpdate`).
+ *      Inline Next.js route handlers never receive `env.SPRIGR`, so an app
+ *      whose provider webhook lands on one has no `data` namespace there.
+ *      Same escape hatch as `emitMarketplaceEvent` and `logToPlatform`:
+ *      `POST ${SPRIGR_PLATFORM_BASE}/internal/wfp/data/partial-update`
+ *      with the `SPRIGR_INSTALL_TOKEN` bearer.
+ *
+ * Unlike `emit` and `log`, this THROWS on failure, matching the host
+ * member and `data.import`: a data write the caller wants the result of
+ * must not be reported as a soft `{ ok: false }` a webhook ack path could
+ * swallow.
+ *
+ * Wire contract (workers/provisioning/src/wfp-data.ts in sprigr-team):
+ *   POST { index?, objects, createIfNotExists? }
+ *   200 { ok: true, updated, skippedMissing, index, physical_indexes? }
+ *   400 { error, detail, index? } with error one of too_many_objects,
+ *       invalid_object, unknown_data_index, shard_field_invalid, ...
+ *   401 / 404 bad token / inactive install
+ */
+
+/** Route the host member and the fallback both call. */
+declare const DATA_PARTIAL_UPDATE_PATH = "/internal/wfp/data/partial-update";
+/** Same per-call cap as `data.import` (`MAX_OBJECTS_PER_CALL` in wfp-data.ts). */
+declare const SPRIGR_DATA_MAX_OBJECTS_PER_CALL = 1000;
+/** One patch: the target `objectID` plus only the fields to merge. */
+type SprigrDataPatch = {
+    objectID: string;
+    [key: string]: unknown;
+};
+/** The body `POST /internal/wfp/data/partial-update` receives. */
+interface SprigrDataPartialUpdateBody {
+    index?: string;
+    objects: SprigrDataPatch[];
+    createIfNotExists: boolean;
+}
+interface PartialUpdateDataOptions extends SprigrDataPartialUpdateOpts {
+    /** Ceiling on the HTTP fallback. No default: a data write is awaited for its result. */
+    timeoutMs?: number;
+}
+/**
+ * Thrown by `buildPartialUpdateBody` (and therefore by `partialUpdateData`)
+ * before anything is sent. `error` is the same code the platform would
+ * answer with, so a caller can branch on one vocabulary.
+ */
+declare class SprigrDataValidationError extends Error {
+    readonly error: string;
+    readonly index?: number;
+    constructor(message: string, fields: {
+        error: string;
+        index?: number;
+    });
+}
+/**
+ * Build the wire body, rejecting what the platform would reject anyway so
+ * the failure is at the call site rather than a 400 in a tail log. Pure.
+ * `createIfNotExists` is always explicit in the output so the default is
+ * visible on the wire and in tests, never inferred server-side.
+ */
+declare function buildPartialUpdateBody(objects: unknown, opts?: SprigrDataPartialUpdateOpts): SprigrDataPartialUpdateBody;
+/**
+ * Whether a partial update could reach the platform at all, by either
+ * transport. Gate a "patch the mirror" step on this rather than on
+ * `env.SPRIGR?.data?.partialUpdate`, which is absent on every inline route
+ * and on wrapper builds older than the platform route.
+ */
+declare function canPartialUpdate(env: WfpBridgeEnv): boolean;
+/**
+ * Merge fields into stored objects from any execution context.
+ *
+ * Prefers the injected `env.SPRIGR.data.partialUpdate`; falls back to the
+ * install-token bridge when it is absent (an inline Next route, or a
+ * wrapper build that predates the member). Validation runs first and
+ * THROWS `SprigrDataValidationError` on a bad batch, before anything is
+ * sent. A platform rejection also throws: the `Error` from
+ * `installTokenPost` carries `.status`, `.error` (the platform's code, e.g.
+ * `shard_field_invalid`) and `.detail`. Nothing here is swallowed.
+ *
+ *   // before: two calls and a whole-object rewrite
+ *   const { object } = await env.SPRIGR.data.get(orderId, { index: 'orders' });
+ *   await env.SPRIGR.data.import([{ ...object, status: 'shipped' }], { index: 'orders' });
+ *
+ *   // after: one call, only the named field changes
+ *   await partialUpdateData(env, [{ objectID: orderId, created_at, status: 'shipped' }], { index: 'orders' });
+ *
+ * (`created_at` rides along because `orders` is date-sharded on it; an
+ * unsharded index needs only `objectID` and the fields to change.)
+ */
+declare function partialUpdateData(env: WfpBridgeEnv, objects: SprigrDataPatch[], opts?: PartialUpdateDataOptions): Promise<SprigrDataPartialUpdateResult>;
+
 /**
  * Caller identity stamped by the platform on agent-initiated WFP dispatches.
  *
@@ -1852,6 +1966,23 @@ interface ManifestDispatchBlock {
         required?: string[];
     }>;
 }
+/**
+ * A manifest tool's DECLARED side-effect class, the `tools[].effects` field of
+ * `sprigr-app.json`. Mirrors the platform's `AppToolEffectsDeclaration`.
+ *
+ * Deliberately the single literal `'write'`, not a `'read' | 'write'` union.
+ * The platform decides a marketplace tool call's dispatch tier from a name
+ * heuristic (a read verb prefix such as `list_` / `get_` / `find_`, anything
+ * else is a write), and the tier controls the dispatch budget, whether a
+ * timeout or a Durable Object disconnect is blind-retried, and whether an
+ * idempotency token is forwarded.
+ *
+ * Declaring `'write'` only ever NARROWS what the app gets: the shorter budget,
+ * no automatic retry, idempotency token forwarded. `'read'` would be the
+ * inverse and is NOT honoured by the platform, so it is not expressible here.
+ * See the platform's decision note 0057.
+ */
+type AppToolEffectsDeclaration = 'write';
 interface ManifestToolLike {
     name: string;
     input_schema?: {
@@ -1862,6 +1993,17 @@ interface ManifestToolLike {
     confirmation?: unknown;
     confirmation_required?: boolean;
     dispatch?: unknown;
+    /**
+     * Force the platform's WRITE dispatch tier for this tool regardless of what
+     * it is named. Declare it when the action mutates and the name does not
+     * obviously say so: `*_or_create_*` composites, `sync_*`, `reconcile_*`, or
+     * a genuine create hiding behind a read verb (`list_and_stage_batch`).
+     *
+     * Omitting it keeps today's behaviour exactly: the name heuristic decides.
+     * A value the platform does not recognise is ignored with a publish-time
+     * warning, never a rejection.
+     */
+    effects?: AppToolEffectsDeclaration;
     [k: string]: unknown;
 }
 interface ManifestLike {
@@ -2094,6 +2236,34 @@ interface SprigrDataIndexOpts {
     /** LOGICAL index name (a `data_indexes` key). See {@link SprigrDataSearchOpts.index}. */
     index?: string;
 }
+/** Options for `env.SPRIGR.data.partialUpdate`. */
+interface SprigrDataPartialUpdateOpts extends SprigrDataIndexOpts {
+    /**
+     * Create an object that does not exist yet from the patch alone. Default
+     * `false`: a patch never creates half an object unless asked, and a
+     * missing target is counted in `skippedMissing` instead of being written.
+     */
+    createIfNotExists?: boolean;
+}
+/** Reply of `env.SPRIGR.data.partialUpdate` (`POST /internal/wfp/data/partial-update`). */
+interface SprigrDataPartialUpdateResult {
+    ok: true;
+    /** Objects whose stored copy changed. */
+    updated: number;
+    /** Objects that did not exist. Only non-zero when `createIfNotExists` is false. */
+    skippedMissing: number;
+    /**
+     * The logical index name for multi-index apps, else the physical index
+     * that was patched (informational).
+     */
+    index: string;
+    /** Multi-index apps: what was patched per physical index/shard. */
+    physical_indexes?: Array<{
+        index: string;
+        shard?: string;
+        updated: number;
+    }>;
+}
 /**
  * The marketplace install's per-company datastore on Sprigr search,
  * injected on `env.SPRIGR` by the platform wrapper for /__sprigr/*
@@ -2155,6 +2325,32 @@ interface SprigrDataApi {
         object: Record<string, unknown> | null;
         index: string;
     }>;
+    /**
+     * Merge fields into existing objects without reading them first. Each
+     * patch MUST carry a string `objectID`. Max 1000 objects per call, the
+     * same cap as `import`. The platform deep-merges each patch onto the
+     * stored object: nested objects recurse, arrays and scalars replace
+     * wholesale, keys you do not send survive. `null` is a value and
+     * overwrites, so strip keys you do not mean to change rather than
+     * sending them as `null` or `undefined`-then-serialised.
+     *
+     * `createIfNotExists` defaults to `false`: a patch never creates half an
+     * object unless asked, and a missing target is counted in
+     * `skippedMissing`. On a hash- or date-sharded logical index every patch
+     * MUST carry the `shard_field` value, or the WHOLE batch fails with
+     * `shard_field_invalid`: a patch cannot be routed to its shard otherwise,
+     * and the platform will not probe every shard to find it. The response's
+     * `physical_indexes` lists what was patched per shard.
+     *
+     * `?`-optional because wrapper builds older than the platform route
+     * predate it. Feature-detect, or call this package's
+     * `partialUpdateData(env, objects, opts)`, which uses this member when
+     * present and the install-token bridge otherwise.
+     */
+    partialUpdate?(objects: Array<{
+        objectID: string;
+        [key: string]: unknown;
+    }>, opts?: SprigrDataPartialUpdateOpts): Promise<SprigrDataPartialUpdateResult>;
     /**
      * Delete objects by objectID (mirror maintenance for source-side
      * deletions). Idempotent: unknown ids and never-imported indexes are a
@@ -2343,4 +2539,4 @@ interface ExecutionContextLike {
 }
 type HandlerFn<TArgs, TResult> = (args: TArgs, env: Record<string, unknown>, ctx?: ExecutionContextLike) => Promise<TResult>;
 
-export { APPROVAL_GRANTED_KEY, type Actor, type AppApprovalEnvelope, type AppFileListItem, type AppFileUrlArgs, type AppFileUrlResult, type AppFilesEnv, type AppUndoEnvelope, type ApplyPoliciesOptions, type ApprovalGateOptions, type ApprovalSpec, type ArchiveOfferOptions, type ArchiveOfferRefusal, type CaptureJournal, type ConfirmCondition, type ConfirmRule, type ConfirmationPolicy, type D1Like, type D1PreparedStatementLike, DEFAULT_EMIT_TIMEOUT_MS, DEFAULT_LOG_TIMEOUT_MS, DEFAULT_MAX_FILE_BYTES, DEFAULT_MONEY_FIELDS, DEFAULT_WRITE_PREFIXES, type DerivePolicyOptions, type DerivedPolicy, type DispatcherApprovalGate, type DispatcherApprovalOptions, type EmitMarketplaceEventOptions, type EmitResult, type EmitTransport, type EventArgs, type ExecutionContextLike, type FetchFileResult, type FetchWithRetryOptions, type GetAppFileResult, type HandlerFn, type InboxOwner, type InstallBridge, InvalidUndoEnvelopeError, type JournalRowLike, type LogToPlatformOptions, type ManifestDispatchBlock, type ManifestLike, type ManifestToolLike, type MarketplaceEventEmitOpts, type MarketplaceEventSourceIntegration, NotConnectedError, type OAuthBouncerSignals, type OAuthState, type OfferUndoArgs, type PlatformHostEnv, type PolicyCheckInput, type PolicySource, type PutAppFileArgs, type PutAppFileResult, type PutAppFileStreamArgs, type RequireApprovalOptions, type ResolveViewerOptions, type RestoreResult, type RestoreSpec, SPRIGR_LOG_LEVELS, SPRIGR_LOG_LIMITS, type ScheduleArgs, type SprigrDataAggregationCell, type SprigrDataAggregationResult, type SprigrDataAggregationSpec, type SprigrDataApi, type SprigrDataIndexOpts, type SprigrDataSearchOpts, type SprigrDataSearchResult, type SprigrFilesApi, type SprigrFilesApiWithEdit, type SprigrFilesCreateInput, type SprigrFilesCreateResult, type SprigrFilesEditInput, type SprigrFilesEditResult, type SprigrFilesJobResult, type SprigrLogEntry, type SprigrLogFn, type SprigrLogLevel, type SprigrLogResult, SprigrLogValidationError, type ToolArgs, type ToolHandler, type ToolResult, type ToolWrapperOptions, UNIT_SEP, type UndoApplyOptions, type UndoApplyResult, type UndoCaptureSpec, type UndoFidelity, VIEWER_ANONYMOUS, VIEWER_CONTEXT_HEADER, VIEWER_PLATFORM_USER_ID_HEADER, VIEWER_ROLE_HEADER, VIEWER_USER_ID_HEADER, type VerbRule, type ViewerContext, type ViewerContextFailure, type ViewerContextVerification, type ViewerEnv, type WebhookArgs, type WfpBridgeEnv, type WfpEmitReply, actorKey, actorTool, appFileUrl, applyConfirmationPolicies, approvalHash, archiveOfferRefusal, base64ToBytes, buildConfirmationPolicy, buildMarketplaceWebhookUrl, bytesToBase64, canEmit, canLog, checkConfirmationPolicy, commonDestructiveVerbs, constantTimeEqual, createMarketplaceEmitter, createToolWrappers, decodeState, deleteAppFile, deriveConfirmationPolicy, describeMissingBridge, dispatcherApproval, emitMarketplaceEvent, encodeState, fetchFileAsBase64, fetchFileBytes, fetchWithRetry, fullWarning, getAppFile, hmacSha256Hex, installTokenPost, isNotConnectedError, isStagingHost, listAppFiles, logToPlatform, manifestIsFresh, offerUndo, overlaySprigr, ownerFromActorKey, parseActor, putAppFile, putAppFileStream, randomHex, recreatedWarning, refuseWithoutForce, requireApproval, resolveInstallBridge, resolveOAuthBouncerBase, resolveOAuthBouncerCallbackUrl, resolvePlatformWebhookBase, resolveViewerContext, resolveViewerUserId, runUndoApply, safeCapture, seq, serializeManifest, set, tool, undoEnvelope, validateLogEntries, validateLogEntry, verifyViewerToken, withSprigrEmitFallback, withSprigrLogFallback };
+export { APPROVAL_GRANTED_KEY, type Actor, type AppApprovalEnvelope, type AppFileListItem, type AppFileUrlArgs, type AppFileUrlResult, type AppFilesEnv, type AppToolEffectsDeclaration, type AppUndoEnvelope, type ApplyPoliciesOptions, type ApprovalGateOptions, type ApprovalSpec, type ArchiveOfferOptions, type ArchiveOfferRefusal, type CaptureJournal, type ConfirmCondition, type ConfirmRule, type ConfirmationPolicy, type D1Like, type D1PreparedStatementLike, DATA_PARTIAL_UPDATE_PATH, DEFAULT_EMIT_TIMEOUT_MS, DEFAULT_LOG_TIMEOUT_MS, DEFAULT_MAX_FILE_BYTES, DEFAULT_MONEY_FIELDS, DEFAULT_WRITE_PREFIXES, type DerivePolicyOptions, type DerivedPolicy, type DispatcherApprovalGate, type DispatcherApprovalOptions, type EmitMarketplaceEventOptions, type EmitResult, type EmitTransport, type EventArgs, type ExecutionContextLike, type FetchFileResult, type FetchWithRetryOptions, type GetAppFileResult, type HandlerFn, type InboxOwner, type InstallBridge, InvalidUndoEnvelopeError, type JournalRowLike, type LogToPlatformOptions, type ManifestDispatchBlock, type ManifestLike, type ManifestToolLike, type MarketplaceEventEmitOpts, type MarketplaceEventSourceIntegration, NotConnectedError, type OAuthBouncerSignals, type OAuthState, type OfferUndoArgs, type PartialUpdateDataOptions, type PlatformHostEnv, type PolicyCheckInput, type PolicySource, type PutAppFileArgs, type PutAppFileResult, type PutAppFileStreamArgs, type RequireApprovalOptions, type ResolveViewerOptions, type RestoreResult, type RestoreSpec, SPRIGR_DATA_MAX_OBJECTS_PER_CALL, SPRIGR_LOG_LEVELS, SPRIGR_LOG_LIMITS, type ScheduleArgs, type SprigrDataAggregationCell, type SprigrDataAggregationResult, type SprigrDataAggregationSpec, type SprigrDataApi, type SprigrDataIndexOpts, type SprigrDataPartialUpdateBody, type SprigrDataPartialUpdateOpts, type SprigrDataPartialUpdateResult, type SprigrDataPatch, type SprigrDataSearchOpts, type SprigrDataSearchResult, SprigrDataValidationError, type SprigrFilesApi, type SprigrFilesApiWithEdit, type SprigrFilesCreateInput, type SprigrFilesCreateResult, type SprigrFilesEditInput, type SprigrFilesEditResult, type SprigrFilesJobResult, type SprigrLogEntry, type SprigrLogFn, type SprigrLogLevel, type SprigrLogResult, SprigrLogValidationError, type ToolArgs, type ToolHandler, type ToolResult, type ToolWrapperOptions, UNIT_SEP, type UndoApplyOptions, type UndoApplyResult, type UndoCaptureSpec, type UndoFidelity, VIEWER_ANONYMOUS, VIEWER_CONTEXT_HEADER, VIEWER_PLATFORM_USER_ID_HEADER, VIEWER_ROLE_HEADER, VIEWER_USER_ID_HEADER, type VerbRule, type ViewerContext, type ViewerContextFailure, type ViewerContextVerification, type ViewerEnv, type WebhookArgs, type WfpBridgeEnv, type WfpEmitReply, actorKey, actorTool, appFileUrl, applyConfirmationPolicies, approvalHash, archiveOfferRefusal, base64ToBytes, buildConfirmationPolicy, buildMarketplaceWebhookUrl, buildPartialUpdateBody, bytesToBase64, canEmit, canLog, canPartialUpdate, checkConfirmationPolicy, commonDestructiveVerbs, constantTimeEqual, createMarketplaceEmitter, createToolWrappers, decodeState, deleteAppFile, deriveConfirmationPolicy, describeMissingBridge, dispatcherApproval, emitMarketplaceEvent, encodeState, fetchFileAsBase64, fetchFileBytes, fetchWithRetry, fullWarning, getAppFile, hmacSha256Hex, installTokenPost, isNotConnectedError, isStagingHost, listAppFiles, logToPlatform, manifestIsFresh, offerUndo, overlaySprigr, ownerFromActorKey, parseActor, partialUpdateData, putAppFile, putAppFileStream, randomHex, recreatedWarning, refuseWithoutForce, requireApproval, resolveInstallBridge, resolveOAuthBouncerBase, resolveOAuthBouncerCallbackUrl, resolvePlatformWebhookBase, resolveViewerContext, resolveViewerUserId, runUndoApply, safeCapture, seq, serializeManifest, set, tool, undoEnvelope, validateLogEntries, validateLogEntry, verifyViewerToken, withSprigrEmitFallback, withSprigrLogFallback };

package/dist/index.js

@@ -509,6 +509,91 @@ function withSprigrLogFallback(env, opts) {
   return overlaySprigr(env, { ...existing, log });
 }
 
+// src/platform-data.ts
+var DATA_PARTIAL_UPDATE_PATH = "/internal/wfp/data/partial-update";
+var SPRIGR_DATA_MAX_OBJECTS_PER_CALL = 1e3;
+var SprigrDataValidationError = class extends Error {
+  error;
+  index;
+  constructor(message, fields) {
+    super(message);
+    this.name = "SprigrDataValidationError";
+    this.error = fields.error;
+    if (fields.index !== void 0) this.index = fields.index;
+  }
+};
+function buildPartialUpdateBody(objects, opts) {
+  const at = "env.SPRIGR.data.partialUpdate";
+  if (!Array.isArray(objects) || objects.length === 0) {
+    throw new SprigrDataValidationError(`${at}: objects must be a non-empty array`, {
+      error: "invalid_object"
+    });
+  }
+  if (objects.length > SPRIGR_DATA_MAX_OBJECTS_PER_CALL) {
+    throw new SprigrDataValidationError(
+      `${at}: at most ${SPRIGR_DATA_MAX_OBJECTS_PER_CALL} objects per call (got ${objects.length}); nothing was sent. Split the batch.`,
+      { error: "too_many_objects" }
+    );
+  }
+  for (let i = 0; i < objects.length; i++) {
+    const o = objects[i];
+    if (!o || typeof o !== "object" || Array.isArray(o)) {
+      throw new SprigrDataValidationError(`${at}: objects[${i}] must be an object`, {
+        error: "invalid_object",
+        index: i
+      });
+    }
+    const id = o.objectID;
+    if (typeof id !== "string" || id.length === 0) {
+      throw new SprigrDataValidationError(
+        `${at}: objects[${i}].objectID must be a non-empty string (a patch has to name its target)`,
+        { error: "invalid_object", index: i }
+      );
+    }
+  }
+  if (opts?.index !== void 0 && (typeof opts.index !== "string" || opts.index.length === 0)) {
+    throw new SprigrDataValidationError(`${at}: index must be a non-empty string when given`, {
+      error: "unknown_data_index"
+    });
+  }
+  return {
+    ...opts?.index !== void 0 ? { index: opts.index } : {},
+    objects,
+    createIfNotExists: opts?.createIfNotExists === true
+  };
+}
+function bindingPartialUpdate(env) {
+  const data = env.SPRIGR?.data;
+  return typeof data?.partialUpdate === "function" ? data.partialUpdate.bind(data) : null;
+}
+function canPartialUpdate(env) {
+  return bindingPartialUpdate(env) !== null || resolveInstallBridge(env) !== null;
+}
+function describeMissingDataPath(env) {
+  const base = typeof env.SPRIGR_PLATFORM_BASE === "string" && env.SPRIGR_PLATFORM_BASE ? "set" : "unset";
+  const token = typeof env.SPRIGR_INSTALL_TOKEN === "string" && env.SPRIGR_INSTALL_TOKEN ? "set" : "unset";
+  return `no_data_path (SPRIGR.data.partialUpdate absent, SPRIGR_PLATFORM_BASE=${base}, SPRIGR_INSTALL_TOKEN=${token})`;
+}
+async function partialUpdateData(env, objects, opts) {
+  const { timeoutMs, ...dataOpts } = opts ?? {};
+  const body = buildPartialUpdateBody(objects, dataOpts);
+  const injected = bindingPartialUpdate(env);
+  if (injected) {
+    return injected(body.objects, {
+      ...body.index !== void 0 ? { index: body.index } : {},
+      createIfNotExists: body.createIfNotExists
+    });
+  }
+  const bridge = resolveInstallBridge(env);
+  if (!bridge) {
+    throw new Error(`env.SPRIGR.data.partialUpdate unavailable: ${describeMissingDataPath(env)}`);
+  }
+  return await installTokenPost(bridge, DATA_PARTIAL_UPDATE_PATH, body, {
+    label: "data.partialUpdate",
+    ...timeoutMs !== void 0 ? { timeoutMs } : {}
+  });
+}
+
 // src/actor.ts
 function parseActor(args) {
   if (!args || typeof args !== "object") return void 0;
@@ -1363,6 +1448,7 @@ function commonDestructiveVerbs(subject) {
 }
 export {
   APPROVAL_GRANTED_KEY,
+  DATA_PARTIAL_UPDATE_PATH,
   DEFAULT_EMIT_TIMEOUT_MS,
   DEFAULT_LOG_TIMEOUT_MS,
   DEFAULT_MAX_FILE_BYTES,
@@ -1370,8 +1456,10 @@ export {
   DEFAULT_WRITE_PREFIXES,
   InvalidUndoEnvelopeError,
   NotConnectedError,
+  SPRIGR_DATA_MAX_OBJECTS_PER_CALL,
   SPRIGR_LOG_LEVELS,
   SPRIGR_LOG_LIMITS,
+  SprigrDataValidationError,
   SprigrLogValidationError,
   UNIT_SEP,
   VIEWER_ANONYMOUS,
@@ -1388,9 +1476,11 @@ export {
   base64ToBytes,
   buildConfirmationPolicy,
   buildMarketplaceWebhookUrl,
+  buildPartialUpdateBody,
   bytesToBase64,
   canEmit,
   canLog,
+  canPartialUpdate,
   checkConfirmationPolicy,
   commonDestructiveVerbs,
   constantTimeEqual,
@@ -1419,6 +1509,7 @@ export {
   overlaySprigr,
   ownerFromActorKey,
   parseActor,
+  partialUpdateData,
   putAppFile,
   putAppFileStream,
   randomHex,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sprigr/apps-app-sdk",
-  "version": "0.10.1",
+  "version": "0.12.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",