@sprigr/apps-app-sdk 0.12.0 → 0.14.0

package/dist/index.d.ts

@@ -669,6 +669,12 @@ declare function withSprigrLogFallback<E extends WfpBridgeEnv & object>(env: E,
  * 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`.
  *
+ * `withAcl: true` is a narrower mode: it re-stamps `acl_principals` on rows
+ * already in the app's `-acl-files` index and nothing else. Every patch must
+ * be exactly `{ objectID, acl_principals }`, and `createIfNotExists` and
+ * `index` cannot be combined with it. Content is written only by an ACL
+ * `import`, whole.
+ *
  * This module carries two things:
  *
  *   1. `buildPartialUpdateBody`, the wire body both transports send, with
@@ -687,10 +693,13 @@ declare function withSprigrLogFallback<E extends WfpBridgeEnv & object>(env: E,
  * swallow.
  *
  * Wire contract (workers/provisioning/src/wfp-data.ts in sprigr-team):
- *   POST { index?, objects, createIfNotExists? }
+ *   POST { index?, objects, createIfNotExists?, withAcl? }
  *   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, ...
+ *       invalid_object, unknown_data_index, shard_field_invalid,
+ *       acl_partial_update_fields, acl_partial_update_create_unsupported,
+ *       acl_index_combination_unsupported, missing_acl_principals,
+ *       invalid_acl_principal, ...
  *   401 / 404 bad token / inactive install
  */
 
@@ -708,6 +717,8 @@ interface SprigrDataPartialUpdateBody {
     index?: string;
     objects: SprigrDataPatch[];
     createIfNotExists: boolean;
+    /** Present (and true) only for an ACL re-stamp. */
+    withAcl?: true;
 }
 interface PartialUpdateDataOptions extends SprigrDataPartialUpdateOpts {
     /** Ceiling on the HTTP fallback. No default: a data write is awaited for its result. */
@@ -2244,6 +2255,17 @@ interface SprigrDataPartialUpdateOpts extends SprigrDataIndexOpts {
      * missing target is counted in `skippedMissing` instead of being written.
      */
     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.
+     */
+    withAcl?: boolean;
 }
 /** Reply of `env.SPRIGR.data.partialUpdate` (`POST /internal/wfp/data/partial-update`). */
 interface SprigrDataPartialUpdateResult {
@@ -2379,6 +2401,12 @@ interface SprigrDataApi {
  * URL the upstream deletes after a short retention window) so the URL your
  * app hands back keeps resolving.
  *
+ * Per-user storage (sprigr-team#9621): keys under the manifest's
+ * `actor_scoped_storage_prefixes` are stored and resolved per CALLER by the
+ * platform, from the signed actor the wrapper forwards on every call. Keep
+ * using app-relative keys; never add your own owner tag. A call with no actor
+ * may only `list` / `delete` there (maintenance), never read.
+ *
  * This is the in-isolate bridge surface, injected on `env.SPRIGR` for
  * `/__sprigr/*` tool / webhook / event handlers. The standalone
  * `putAppFileStream` / `appFileUrl` helpers in this package call the same
@@ -2418,6 +2446,75 @@ interface SprigrFilesApi {
         expires_at: number;
         key: string;
     }>;
+    /**
+     * Buffered put of base64 bytes (cap 10 MB); prefer `putStream` for anything
+     * large. Optional: absent on wrapper builds before sprigr-team#9621, so
+     * feature-detect. Throws with `err.code` / `err.status` on a refusal.
+     */
+    put?(key: string, base64: string, opts?: {
+        contentType?: string;
+        filename?: string;
+    }): Promise<{
+        ok: boolean;
+        key: string;
+        bytes: number;
+        contentType: string;
+    }>;
+    /** Read a stored object back as base64. Throws `err.code === 'not_found'`
+     *  (404) when absent. Optional: see `put`. */
+    get?(key: string): Promise<{
+        ok: boolean;
+        key: string;
+        base64: string;
+        contentType: string;
+        filename?: string;
+        bytes: number;
+    }>;
+    /**
+     * List stored keys under an app-relative prefix, 1000 per page; pass the
+     * returned `cursor` for the next page. On a call with no actor (a schedule,
+     * webhook or event handler), a prefix under `actor_scoped_storage_prefixes`
+     * lists EVERY user's copies, each entry carrying an opaque `owner_ref`
+     * (`owner_scope: 'all_owners'`); with `ownerless: true` it lists the copies
+     * written there before the prefix was declared (`owner_scope: 'ownerless'`).
+     * Optional: see `put`.
+     */
+    list?(prefix?: string, opts?: {
+        cursor?: string;
+        ownerless?: boolean;
+    }): Promise<SprigrFilesListResult>;
+    /**
+     * Delete a stored key. On a call with no actor, a per-user key needs the
+     * `owner_ref` (or `ownerless: true`) a maintenance `list` returned; on a call
+     * made for a user both are ignored and that user's own copy is deleted.
+     * Optional: see `put`.
+     */
+    delete?(key: string, opts?: {
+        owner_ref?: string;
+        ownerless?: boolean;
+    }): Promise<{
+        ok: boolean;
+        key: string;
+    }>;
+}
+/** One entry of `env.SPRIGR.files.list`. `owner_ref` / `ownerless` appear only
+ *  on a maintenance listing of a per-user prefix (sprigr-team#9621). */
+interface SprigrFilesListItem {
+    key: string;
+    bytes: number;
+    uploaded?: string;
+    filename?: string;
+    contentType?: string;
+    owner_ref?: string;
+    ownerless?: boolean;
+}
+/** Result of `env.SPRIGR.files.list`. */
+interface SprigrFilesListResult {
+    ok: boolean;
+    files: SprigrFilesListItem[];
+    truncated: boolean;
+    cursor?: string;
+    owner_scope?: 'all_owners' | 'ownerless';
 }
 /**
  * Platform document-engine bridge types (`env.SPRIGR.files.edit` / `.create`
@@ -2539,4 +2636,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 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 };
+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 SprigrFilesListItem, type SprigrFilesListResult, 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

@@ -512,6 +512,7 @@ function withSprigrLogFallback(env, opts) {
 // src/platform-data.ts
 var DATA_PARTIAL_UPDATE_PATH = "/internal/wfp/data/partial-update";
 var SPRIGR_DATA_MAX_OBJECTS_PER_CALL = 1e3;
+var ACL_INDEX_SUFFIX = "-acl-files";
 var SprigrDataValidationError = class extends Error {
   error;
   index;
@@ -556,12 +557,51 @@ function buildPartialUpdateBody(objects, opts) {
       error: "unknown_data_index"
     });
   }
+  const withAcl = opts?.withAcl === true;
+  if (withAcl) checkAclRestamp(objects, opts, at);
   return {
     ...opts?.index !== void 0 ? { index: opts.index } : {},
     objects,
-    createIfNotExists: opts?.createIfNotExists === true
+    createIfNotExists: opts?.createIfNotExists === true,
+    ...withAcl ? { withAcl: true } : {}
   };
 }
+function checkAclRestamp(objects, opts, at) {
+  if (opts?.createIfNotExists === true) {
+    throw new SprigrDataValidationError(
+      `${at}: withAcl only re-stamps existing rows; createIfNotExists would create a row with principals and no content`,
+      { error: "acl_partial_update_create_unsupported" }
+    );
+  }
+  if (opts?.index !== void 0) {
+    throw new SprigrDataValidationError(`${at}: withAcl targets the reserved -acl-files index and cannot be combined with index`, {
+      error: "acl_index_combination_unsupported"
+    });
+  }
+  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) {
+      throw new SprigrDataValidationError(
+        `${at}: objects[${i}] carries "${extra}"; a withAcl partial update sets only objectID and acl_principals (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
+      });
+    }
+  }
+}
+function assertAclIndex(result) {
+  if (typeof result?.index === "string" && result.index.endsWith(ACL_INDEX_SUFFIX)) return result;
+  throw new Error(
+    `data.partialUpdate withAcl landed on ${String(result?.index)}, not the ${ACL_INDEX_SUFFIX} index: this app was built by a platform wrapper that drops withAcl. Republish the app to pick up the current wrapper.`
+  );
+}
 function bindingPartialUpdate(env) {
   const data = env.SPRIGR?.data;
   return typeof data?.partialUpdate === "function" ? data.partialUpdate.bind(data) : null;
@@ -579,10 +619,12 @@ async function partialUpdateData(env, objects, opts) {
   const body = buildPartialUpdateBody(objects, dataOpts);
   const injected = bindingPartialUpdate(env);
   if (injected) {
-    return injected(body.objects, {
+    const result = await injected(body.objects, {
       ...body.index !== void 0 ? { index: body.index } : {},
-      createIfNotExists: body.createIfNotExists
+      createIfNotExists: body.createIfNotExists,
+      ...body.withAcl ? { withAcl: true } : {}
     });
+    return body.withAcl ? assertAclIndex(result) : result;
   }
   const bridge = resolveInstallBridge(env);
   if (!bridge) {

package/package.json

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