@sprigr/apps-app-sdk 0.18.0 → 0.19.0

package/README.md

@@ -15,7 +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.
+- `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`. With `{ withAcl: true }` it patches existing rows of the app's `-acl-files` index: each object carries `objectID` plus `acl_principals` and/or label fields the manifest declares in `data_index.acl_patchable_fields` (never `content`), and an object that omits `acl_principals` keeps its stored ones. `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

@@ -2763,14 +2763,20 @@ interface SprigrDataPartialUpdateOpts extends SprigrDataIndexOpts {
      */
     createIfNotExists?: boolean;
     /**
-     * Re-stamp `acl_principals` on rows already in the app's `-acl-files`
-     * index without rewriting the rest of each row. Every object must be
-     * exactly `{ objectID, acl_principals }` with a non-empty, valid principal
-     * list; `createIfNotExists` and `index` are refused alongside it. Use it
-     * when the source changes who may see an item without reporting the item
-     * as changed (OneDrive's delta omits sharing-only changes). Needs a
-     * platform with sprigr/sprigr-team#9843; older wrappers drop the flag,
-     * which `partialUpdateData` detects and throws on.
+     * Patch rows already in the app's `-acl-files` index without rewriting
+     * the rest of each row. Each object carries `objectID` plus
+     * `acl_principals` (a non-empty, valid list: re-stamps who may see it)
+     * and/or label fields the manifest declares in
+     * `data_index.acl_patchable_fields` (for example `tags`, `properties`).
+     * An object that omits `acl_principals` keeps its stored ones. `content`
+     * is never patchable, and `createIfNotExists` and `index` are refused. Use
+     * it when the source changes who may see an item, or only its labels,
+     * without changing its content (OneDrive's delta omits sharing-only
+     * changes; a Dropbox tag edit leaves the file's text as it was). The
+     * re-stamp needs a platform with sprigr/sprigr-team#9843, label fields one
+     * with #10371 (an older one answers `acl_partial_update_fields`: fall back
+     * to a whole-row import). Older wrappers drop the flag, which
+     * `partialUpdateData` detects and throws on.
      */
     withAcl?: boolean;
 }

package/dist/index.js

@@ -580,19 +580,26 @@ function checkAclRestamp(objects, opts, at) {
   }
   for (let i = 0; i < objects.length; i++) {
     const o = objects[i];
-    const extra = Object.keys(o).find((k) => k !== "objectID" && k !== "acl_principals");
-    if (extra !== void 0) {
+    if ("content" in o) {
       throw new SprigrDataValidationError(
-        `${at}: objects[${i}] carries "${extra}"; a withAcl partial update sets only objectID and acl_principals (write content with data.import withAcl)`,
+        `${at}: objects[${i}] carries "content"; a withAcl partial update never writes extracted text (write content with data.import withAcl)`,
         { error: "acl_partial_update_fields", index: i }
       );
     }
-    const principals = o.acl_principals;
-    if (!Array.isArray(principals) || principals.length === 0) {
-      throw new SprigrDataValidationError(`${at}: objects[${i}] needs a non-empty acl_principals: string[]`, {
-        error: "missing_acl_principals",
-        index: i
-      });
+    if (!Object.keys(o).some((k) => k !== "objectID")) {
+      throw new SprigrDataValidationError(
+        `${at}: objects[${i}] sets nothing; send acl_principals or a field your manifest declares in data_index.acl_patchable_fields`,
+        { error: "acl_partial_update_empty", index: i }
+      );
+    }
+    if ("acl_principals" in o) {
+      const principals = o.acl_principals;
+      if (!Array.isArray(principals) || principals.length === 0) {
+        throw new SprigrDataValidationError(`${at}: objects[${i}] needs a non-empty acl_principals: string[]`, {
+          error: "missing_acl_principals",
+          index: i
+        });
+      }
     }
   }
 }

package/package.json

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