@sprigr/apps-app-sdk 0.25.0 → 0.26.0

package/dist/index.d.ts

@@ -1700,6 +1700,46 @@ interface AppApprovalEnvelope {
      * wrappers.
      */
     unattended?: 'proceed';
+    /**
+     * Lay the card out as the thing being sent: an email with its header and
+     * rendered body, an SMS, a document's rows (sprigr-team decision 0216).
+     * You bind slots to YOUR TOOL'S ARGUMENT NAMES (or dotted paths such as
+     * `input.body` for a dispatcher), and the platform fills them from the
+     * exact arguments it replays on the tap, so the card cannot show one email
+     * while another is sent. Build it with `emailPreview` / `smsPreview` /
+     * `fieldsPreview`. Keep writing `question` and `summary`: a platform
+     * without decision 0216, or a preview that resolves to nothing, falls
+     * back to them.
+     */
+    preview?: ApprovalPreviewSpec;
+}
+/** A slot bound to an argument name or dotted path, or a value you state. */
+type ApprovalPreviewSlot = string | {
+    value: string;
+};
+/** Small facts shown as tags on the card. */
+type ApprovalPreviewFact = 'irreversible' | 'costs_credits' | 'no_signature';
+/** The `_approval.preview` an app declares (sprigr-team decision 0216). */
+interface ApprovalPreviewSpec {
+    kind: 'email' | 'sms' | 'document' | 'calendar' | 'fields';
+    from?: ApprovalPreviewSlot;
+    to?: ApprovalPreviewSlot;
+    cc?: ApprovalPreviewSlot;
+    bcc?: ApprovalPreviewSlot;
+    subject?: ApprovalPreviewSlot;
+    /** Always an argument, never a stated value: the body must be what is sent. */
+    body?: {
+        arg: string;
+        format: 'html' | 'text';
+    };
+    /** Argument holding an array of attachment names or `{ name, size }`. */
+    attachments?: string;
+    sendAt?: ApprovalPreviewSlot;
+    fields?: Array<{
+        label: string;
+        from: ApprovalPreviewSlot;
+    }>;
+    facts?: ApprovalPreviewFact[];
 }
 /**
  * Platform-stamped marker telling an app that a human approved this call. The
@@ -1789,6 +1829,53 @@ declare const APPROVAL_PREVIEW_MAX = 600;
  */
 declare function approvalPreview(value: unknown, max?: number): string;
 
+/**
+ * Builders for `_approval.preview` (sprigr-team decision 0216). They return
+ * plain objects; the point is the types and the defaults, so a send tool
+ * declares its card in one line:
+ *
+ *   describe: (_t, a, mailbox) => ({
+ *     question: `Send an email to ${a.to}?`, header: 'Outlook',
+ *     preview: emailPreview({ from: { value: mailbox }, to: 'to', subject: 'subject', body: 'body' }),
+ *   })
+ *
+ * Every string slot is the NAME of one of your tool's arguments (or a dotted
+ * path such as `input.body`). The platform reads the value from the exact
+ * arguments it replays when the person taps, never from anything you send
+ * here, so bind the argument you actually send.
+ */
+
+interface EmailPreviewInput {
+    from?: ApprovalPreviewSlot;
+    to: ApprovalPreviewSlot;
+    cc?: ApprovalPreviewSlot;
+    bcc?: ApprovalPreviewSlot;
+    subject?: ApprovalPreviewSlot;
+    /** Argument name of the body. */
+    body: string;
+    /** Defaults to 'html'. */
+    bodyFormat?: 'html' | 'text';
+    attachments?: string;
+    sendAt?: ApprovalPreviewSlot;
+    /** Defaults to ['irreversible']: a sent email cannot be recalled. */
+    facts?: ApprovalPreviewFact[];
+}
+declare function emailPreview(input: EmailPreviewInput): ApprovalPreviewSpec;
+interface SmsPreviewInput {
+    from?: ApprovalPreviewSlot;
+    to: ApprovalPreviewSlot;
+    /** Argument name of the message text. */
+    body: string;
+    /** Defaults to ['irreversible']. Add 'costs_credits' when it does. */
+    facts?: ApprovalPreviewFact[];
+}
+declare function smsPreview(input: SmsPreviewInput): ApprovalPreviewSpec;
+/** Label and value rows: an invoice's number and total, an event's time. */
+declare function fieldsPreview(kind: 'document' | 'calendar' | 'fields', rows: Array<{
+    label: string;
+    from: ApprovalPreviewSlot;
+}>, extra?: Pick<ApprovalPreviewSpec, 'to' | 'from' | 'subject' | 'facts'>): ApprovalPreviewSpec;
+
 /**
  * Thrown by `undoEnvelope` for a field the platform would reject.
  *
@@ -3570,4 +3657,4 @@ interface ExecutionContextLike {
 }
 type HandlerFn<TArgs, TResult> = (args: TArgs, env: Record<string, unknown>, ctx?: ExecutionContextLike) => Promise<TResult>;
 
-export { ACTOR_RETIRED_HOOK_TOOL, ACTOR_RETIRE_REASONS, APPROVAL_GRANTED_KEY, APPROVAL_PREVIEW_MAX, APP_FILES_ROOT, APP_OWNER_SEGMENT, type Actor, type ActorRetireReason, type ActorRetired, type ActorRetiredHookBody, type ActorRetiredResult, type AppApprovalEnvelope, type AppFileListItem, type AppFileUrlArgs, type AppFileUrlResult, type AppFilesEnv, type AppToolEffectsDeclaration, type AppUndoEnvelope, type ApplyPoliciesOptions, type ApprovalCoverage, type ApprovalGateOptions, type ApprovalSpec, type ArchiveOfferOptions, type ArchiveOfferRefusal, type CallerKeyResolution, type CaptureJournal, type CompanyTimezoneEnv, type ConfirmCondition, type ConfirmRule, type ConfirmationPolicy, type ConnectCompleteRequest, type ConnectCompleteResult, type D1Like, type D1PreparedStatementLike, DATA_DELETE_MAX_IDS, DATA_PARTIAL_UPDATE_PATH, DEFAULT_EMIT_TIMEOUT_MS, DEFAULT_FILE_READ_TIMEOUT_MS, DEFAULT_LOG_TIMEOUT_MS, DEFAULT_MAX_FILE_BYTES, DEFAULT_MONEY_FIELDS, DEFAULT_WRITE_PREFIXES, type DataClient, type DataIdsOpts, type DataListIdsResult, type DataTransport, type DerivePolicyOptions, type DerivedPolicy, type DispatcherApprovalGate, type DispatcherApprovalOptions, type EmitMarketplaceEventOptions, type EmitResult, type EmitTransport, type EncodeStateWithinEnvelopeOptions, type EncodedStateWithinEnvelope, type EventArgs, type ExecutionContextLike, FILE_REF_SOURCES_HELP, type FetchFileResult, type FetchWithRetryOptions, type FileRef, type FileRefContent, type FileRefEnv, FileRefError, type FileRefErrorCode, type FileRefStream, type FileRefVia, type GetAppFileResult, type HandlerFn, INBOX_SEND_CONTRACT_V1, type IdPrefixSpec, type IdSnapshot, type InboxAddress, type InboxAppendRequest, type InboxAppendResult, type InboxChannelDeclaration, type InboxFoldersRequest, type InboxFoldersResult, type InboxOwner, type InboxSendConnection, type InboxSendHandlerImpl, InboxSendRefusal, type InboxSendSupports, type InboxSendV1Args, type InboxSendV1Result, type InstallBridge, InvalidUndoEnvelopeError, type JournalRowLike, type LogToPlatformOptions, type ManifestDispatchBlock, type ManifestLike, type ManifestToolLike, type MarketplaceEventEmitOpts, type MarketplaceEventSourceIntegration, NotConnectedError, OAUTH_STATE_ENVELOPE_MAX_CHARS, type OAuthBouncerSignals, type OAuthState, type OfferUndoArgs, type PartialUpdateDataOptions, type PlatformHostEnv, type PolicyCheckInput, type PolicySource, type PurgeResult, type PutAppFileArgs, type PutAppFileResult, type PutAppFileStreamArgs, type ReadFileRefOptions, type RequireApprovalOptions, type ResolveFileRefOptions, type ResolveViewerOptions, type ResolvedFileRef, type RestoreResult, type RestoreSpec, SPRIGR_DATA_MAX_OBJECTS_PER_CALL, SPRIGR_FILE_HOSTS, SPRIGR_LOG_LEVELS, SPRIGR_LOG_LIMITS, type ScheduleArgs, type SprigrDataAggregationCell, type SprigrDataAggregationResult, type SprigrDataAggregationSpec, type SprigrDataApi, type SprigrDataImportOpts, 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 SprigrInboxApi, type SprigrLogEntry, type SprigrLogFn, type SprigrLogLevel, type SprigrLogResult, SprigrLogValidationError, type SyncedAttachment, type SyncedMessage, 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, WORKSPACE_FILE_HOW_TO, type WebhookArgs, type WfpBridgeEnv, type WfpEmitReply, actorKey, actorRetiredHook, actorTool, agentFileKeyFromUrl, appFileUrl, appKeyFromCallerKey, applyConfirmationPolicies, approvalHash, approvalPreview, approvalRecipients, archiveOfferRefusal, attendedFindings, base64ToBytes, buildConfirmationPolicy, buildMarketplaceWebhookUrl, buildPartialUpdateBody, bytesToBase64, callerKeyRefusal, canEmit, canLog, canPartialUpdate, checkConfirmationPolicy, commonDestructiveVerbs, connectComplete, connectDisconnect, constantTimeEqual, createMarketplaceEmitter, createToolWrappers, decodeState, defineInboxSendHandler, deleteAppFile, deleteSnapshotIds, deriveConfirmationPolicy, describeMissingBridge, dispatcherApproval, emitMarketplaceEvent, encodeState, encodeStateWithinEnvelope, fetchFileAsBase64, fetchFileBytes, fetchWithRetry, fullWarning, getAppFile, getCompanyTimezone, hmacSha256Hex, installTokenPost, isNotConnectedError, isStagingHost, listAppFiles, logToPlatform, makeDataClient, manifestIsFresh, oauthStateEnvelopeOverhead, offerUndo, openFileRef, overlaySprigr, ownerFromActorKey, parseActor, parseActorRetiredArgs, partialUpdateData, purgeIndexByPrefix, putAppFile, putAppFileStream, randomHex, readFileRef, readableStoredKey, recreatedWarning, refuseWithoutForce, requireApproval, resolveFileRef, resolveInstallBridge, resolveOAuthBouncerBase, resolveOAuthBouncerCallbackUrl, resolvePlatformWebhookBase, resolveViewerContext, resolveViewerUserId, runUndoApply, safeCapture, seq, serializeManifest, set, snapshotIndexIds, tool, undoEnvelope, validateLogEntries, validateLogEntry, verifyViewerToken, withSprigrEmitFallback, withSprigrInboxFallback, withSprigrLogFallback };
+export { ACTOR_RETIRED_HOOK_TOOL, ACTOR_RETIRE_REASONS, APPROVAL_GRANTED_KEY, APPROVAL_PREVIEW_MAX, APP_FILES_ROOT, APP_OWNER_SEGMENT, type Actor, type ActorRetireReason, type ActorRetired, type ActorRetiredHookBody, type ActorRetiredResult, type AppApprovalEnvelope, type AppFileListItem, type AppFileUrlArgs, type AppFileUrlResult, type AppFilesEnv, type AppToolEffectsDeclaration, type AppUndoEnvelope, type ApplyPoliciesOptions, type ApprovalCoverage, type ApprovalGateOptions, type ApprovalPreviewFact, type ApprovalPreviewSlot, type ApprovalPreviewSpec, type ApprovalSpec, type ArchiveOfferOptions, type ArchiveOfferRefusal, type CallerKeyResolution, type CaptureJournal, type CompanyTimezoneEnv, type ConfirmCondition, type ConfirmRule, type ConfirmationPolicy, type ConnectCompleteRequest, type ConnectCompleteResult, type D1Like, type D1PreparedStatementLike, DATA_DELETE_MAX_IDS, DATA_PARTIAL_UPDATE_PATH, DEFAULT_EMIT_TIMEOUT_MS, DEFAULT_FILE_READ_TIMEOUT_MS, DEFAULT_LOG_TIMEOUT_MS, DEFAULT_MAX_FILE_BYTES, DEFAULT_MONEY_FIELDS, DEFAULT_WRITE_PREFIXES, type DataClient, type DataIdsOpts, type DataListIdsResult, type DataTransport, type DerivePolicyOptions, type DerivedPolicy, type DispatcherApprovalGate, type DispatcherApprovalOptions, type EmailPreviewInput, type EmitMarketplaceEventOptions, type EmitResult, type EmitTransport, type EncodeStateWithinEnvelopeOptions, type EncodedStateWithinEnvelope, type EventArgs, type ExecutionContextLike, FILE_REF_SOURCES_HELP, type FetchFileResult, type FetchWithRetryOptions, type FileRef, type FileRefContent, type FileRefEnv, FileRefError, type FileRefErrorCode, type FileRefStream, type FileRefVia, type GetAppFileResult, type HandlerFn, INBOX_SEND_CONTRACT_V1, type IdPrefixSpec, type IdSnapshot, type InboxAddress, type InboxAppendRequest, type InboxAppendResult, type InboxChannelDeclaration, type InboxFoldersRequest, type InboxFoldersResult, type InboxOwner, type InboxSendConnection, type InboxSendHandlerImpl, InboxSendRefusal, type InboxSendSupports, type InboxSendV1Args, type InboxSendV1Result, type InstallBridge, InvalidUndoEnvelopeError, type JournalRowLike, type LogToPlatformOptions, type ManifestDispatchBlock, type ManifestLike, type ManifestToolLike, type MarketplaceEventEmitOpts, type MarketplaceEventSourceIntegration, NotConnectedError, OAUTH_STATE_ENVELOPE_MAX_CHARS, type OAuthBouncerSignals, type OAuthState, type OfferUndoArgs, type PartialUpdateDataOptions, type PlatformHostEnv, type PolicyCheckInput, type PolicySource, type PurgeResult, type PutAppFileArgs, type PutAppFileResult, type PutAppFileStreamArgs, type ReadFileRefOptions, type RequireApprovalOptions, type ResolveFileRefOptions, type ResolveViewerOptions, type ResolvedFileRef, type RestoreResult, type RestoreSpec, SPRIGR_DATA_MAX_OBJECTS_PER_CALL, SPRIGR_FILE_HOSTS, SPRIGR_LOG_LEVELS, SPRIGR_LOG_LIMITS, type ScheduleArgs, type SmsPreviewInput, type SprigrDataAggregationCell, type SprigrDataAggregationResult, type SprigrDataAggregationSpec, type SprigrDataApi, type SprigrDataImportOpts, 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 SprigrInboxApi, type SprigrLogEntry, type SprigrLogFn, type SprigrLogLevel, type SprigrLogResult, SprigrLogValidationError, type SyncedAttachment, type SyncedMessage, 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, WORKSPACE_FILE_HOW_TO, type WebhookArgs, type WfpBridgeEnv, type WfpEmitReply, actorKey, actorRetiredHook, actorTool, agentFileKeyFromUrl, appFileUrl, appKeyFromCallerKey, applyConfirmationPolicies, approvalHash, approvalPreview, approvalRecipients, archiveOfferRefusal, attendedFindings, base64ToBytes, buildConfirmationPolicy, buildMarketplaceWebhookUrl, buildPartialUpdateBody, bytesToBase64, callerKeyRefusal, canEmit, canLog, canPartialUpdate, checkConfirmationPolicy, commonDestructiveVerbs, connectComplete, connectDisconnect, constantTimeEqual, createMarketplaceEmitter, createToolWrappers, decodeState, defineInboxSendHandler, deleteAppFile, deleteSnapshotIds, deriveConfirmationPolicy, describeMissingBridge, dispatcherApproval, emailPreview, emitMarketplaceEvent, encodeState, encodeStateWithinEnvelope, fetchFileAsBase64, fetchFileBytes, fetchWithRetry, fieldsPreview, fullWarning, getAppFile, getCompanyTimezone, hmacSha256Hex, installTokenPost, isNotConnectedError, isStagingHost, listAppFiles, logToPlatform, makeDataClient, manifestIsFresh, oauthStateEnvelopeOverhead, offerUndo, openFileRef, overlaySprigr, ownerFromActorKey, parseActor, parseActorRetiredArgs, partialUpdateData, purgeIndexByPrefix, putAppFile, putAppFileStream, randomHex, readFileRef, readableStoredKey, recreatedWarning, refuseWithoutForce, requireApproval, resolveFileRef, resolveInstallBridge, resolveOAuthBouncerBase, resolveOAuthBouncerCallbackUrl, resolvePlatformWebhookBase, resolveViewerContext, resolveViewerUserId, runUndoApply, safeCapture, seq, serializeManifest, set, smsPreview, snapshotIndexIds, tool, undoEnvelope, validateLogEntries, validateLogEntry, verifyViewerToken, withSprigrEmitFallback, withSprigrInboxFallback, withSprigrLogFallback };

package/dist/index.js

@@ -1396,6 +1396,34 @@ function approvalPreview(value, max = APPROVAL_PREVIEW_MAX) {
   return text.length > max ? `${text.slice(0, max)}\u2026` : text;
 }
 
+// src/write-protection/approval-preview.ts
+function emailPreview(input) {
+  return {
+    kind: "email",
+    ...input.from !== void 0 ? { from: input.from } : {},
+    to: input.to,
+    ...input.cc !== void 0 ? { cc: input.cc } : {},
+    ...input.bcc !== void 0 ? { bcc: input.bcc } : {},
+    ...input.subject !== void 0 ? { subject: input.subject } : {},
+    body: { arg: input.body, format: input.bodyFormat ?? "html" },
+    ...input.attachments !== void 0 ? { attachments: input.attachments } : {},
+    ...input.sendAt !== void 0 ? { sendAt: input.sendAt } : {},
+    facts: input.facts ?? ["irreversible"]
+  };
+}
+function smsPreview(input) {
+  return {
+    kind: "sms",
+    ...input.from !== void 0 ? { from: input.from } : {},
+    to: input.to,
+    body: { arg: input.body, format: "text" },
+    facts: input.facts ?? ["irreversible"]
+  };
+}
+function fieldsPreview(kind, rows, extra = {}) {
+  return { kind, ...extra, fields: rows };
+}
+
 // src/write-protection/undo-envelope.ts
 var InvalidUndoEnvelopeError = class extends Error {
   constructor(message2) {
@@ -2308,12 +2336,14 @@ export {
   deriveConfirmationPolicy,
   describeMissingBridge,
   dispatcherApproval,
+  emailPreview,
   emitMarketplaceEvent,
   encodeState,
   encodeStateWithinEnvelope,
   fetchFileAsBase64,
   fetchFileBytes,
   fetchWithRetry,
+  fieldsPreview,
   fullWarning,
   getAppFile,
   getCompanyTimezone,
@@ -2354,6 +2384,7 @@ export {
   seq,
   serializeManifest,
   set,
+  smsPreview,
   snapshotIndexIds,
   tool,
   undoEnvelope,

package/package.json

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