@sprigr/apps-app-sdk 0.29.0 → 0.31.0

package/dist/index.d.ts

@@ -976,6 +976,97 @@ declare function logToPlatform(env: WfpBridgeEnv, input: SprigrLogEntry | Sprigr
  */
 declare function withSprigrLogFallback<E extends WfpBridgeEnv & object>(env: E, opts?: LogToPlatformOptions): E;
 
+/**
+ * `env.SPRIGR.report`: an app files a deduped platform report about a problem
+ * it found (sprigr-team decision 0262, sprigr-team#12208). The platform route
+ * is `POST /internal/wfp/report`; it stamps the app, install, installing
+ * company and publisher, scrubs credentials from title and detail, dedupes one
+ * report per app + key per window, caps new filings (5 per install per day,
+ * 20 per app per hour), and files severity 'critical' as 'high'.
+ *
+ * This module carries:
+ *   1. The types of the host member, so a call site is typed.
+ *   2. The route's limits, so an app can shape its input before calling.
+ *   3. The inline-route fallback (`reportToPlatform`), for code that runs
+ *      where the host member is absent (an inline Next route).
+ *
+ * Unlike `env.SPRIGR.log`, the host member does NOT validate client-side and
+ * NEVER throws or rejects: a refused call resolves `{ ok: false, error }`
+ * with the route's error code. `reportToPlatform` keeps that contract.
+ */
+
+/** Requested severity. The platform files 'critical' as 'high'. */
+type SprigrReportSeverity = 'low' | 'medium' | 'high' | 'critical';
+declare const SPRIGR_REPORT_SEVERITIES: readonly SprigrReportSeverity[];
+interface SprigrReportInput {
+    /** Stable identifier for this problem, e.g. "skip_empty_with_rows". Dedupe key per app. */
+    key: string;
+    /** One line, at most 200 chars. */
+    title: string;
+    /** Optional detail, at most 8000 chars. */
+    detail?: string;
+    /** Default 'medium'. */
+    severity?: SprigrReportSeverity;
+    /** Dedupe window in seconds. Default 86400, clamped to 3600..604800. */
+    ttlSeconds?: number;
+}
+/**
+ * What the host member resolves. It never rejects.
+ * - `{ ok: true, status }`: filed, deduped (already filed in this window), or
+ *   rate_limited (a cap was reached; nothing filed).
+ * - `{ ok: false, status: 'failed' }`: the platform accepted the call but the
+ *   filing itself failed.
+ * - `{ ok: false, error }`: refused (`invalid_key`, `title_too_long`, ...),
+ *   a transport failure, `bindings_not_configured`, or `home_read_only` on a
+ *   Home dispatch.
+ */
+type SprigrReportResult = {
+    ok: true;
+    status: 'filed' | 'deduped' | 'rate_limited';
+} | {
+    ok: false;
+    status: 'failed';
+} | {
+    ok: false;
+    error: string;
+    detail?: string;
+    status?: number;
+};
+/** Signature of the injected `env.SPRIGR.report`. */
+type SprigrReportFn = (input: SprigrReportInput) => Promise<SprigrReportResult>;
+/** Mirrors the platform route (sprigr-team `workers/provisioning/src/wfp-report.ts`). */
+declare const SPRIGR_REPORT_LIMITS: Readonly<{
+    keyPattern: RegExp;
+    maxTitleChars: 200;
+    maxDetailChars: 8000;
+    defaultTtlSeconds: number;
+    minTtlSeconds: 3600;
+    maxTtlSeconds: number;
+    capPerInstallPerDay: 5;
+    capPerAppPerHour: 20;
+}>;
+declare const DEFAULT_REPORT_TIMEOUT_MS = 5000;
+interface ReportToPlatformOptions {
+    /** Override the 5s ceiling on the HTTP fallback. */
+    timeoutMs?: number;
+    /** `ctx.waitUntil` from the route handler, so the fallback fetch outlives the response. */
+    waitUntil?: (p: Promise<unknown>) => void;
+}
+/** Whether a report could reach the platform by either transport. */
+declare function canReport(env: WfpBridgeEnv): boolean;
+/**
+ * File a platform report from any execution context. Prefers the injected
+ * `env.SPRIGR.report`; falls back to the install-token bridge when it is
+ * absent. Never throws and never rejects.
+ *
+ *   const r = await reportToPlatform(env, {
+ *     key: 'skip_empty_with_rows',
+ *     title: 'Upstream returned rows on a page marked empty',
+ *     detail: `page ${page}, ${rows.length} rows`,
+ *   }, { waitUntil: ctx.waitUntil.bind(ctx) });
+ */
+declare function reportToPlatform(env: WfpBridgeEnv, input: SprigrReportInput, opts?: ReportToPlatformOptions): Promise<SprigrReportResult>;
+
 /**
  * `env.SPRIGR.data.partialUpdate` from BOTH execution contexts.
  *
@@ -3150,6 +3241,30 @@ declare function hasHtmlMarkup(body: string): boolean;
  */
 declare function emailBodyHtml(body: string): string;
 
+/**
+ * The sending person's Inbox signature on mail an app sends as them
+ * (sprigr-team decision 0255): one rule for every mail app, so the
+ * microsoft-365 and google-workspace apps cannot drift apart.
+ *
+ * The platform resolves the person from the dispatch's signed actor
+ * assertion (`env.SPRIGR.me.signature`); this only decides whether to append.
+ * It appends when the bridge offers `me.signature`, the answer is ok and
+ * carries html, the signature belongs to `senderPlatformUserId` (the owner of
+ * the mailbox the mail goes out from), and the body does not already contain
+ * it. The CALLER decides the mailbox: never call this for a shared or
+ * delegated mailbox, nor for mail the Inbox composer wrote (it already seeded
+ * the signature). Any refusal, missing bridge or failure returns the body
+ * unchanged; a signature is never a reason to fail a send.
+ */
+
+declare function withSenderSignature(sprigr: {
+    me?: Pick<SprigrMeApi, 'signature'>;
+} | undefined, args: {
+    html: string;
+    channel: string;
+    senderPlatformUserId: string | undefined;
+}): Promise<string>;
+
 /**
  * @sprigr/apps-app-sdk
  *
@@ -3526,6 +3641,42 @@ interface SprigrAssertionsApi {
      */
     mint(audience: string): Promise<SprigrAssertionMintResult>;
 }
+/** The `error` values {@link SprigrMeApi.signature} can resolve with. */
+type SprigrMeSignatureError = 'no_person' | 'actor_unverified' | 'invalid' | 'unavailable';
+/**
+ * The result of {@link SprigrMeApi.signature} (sprigr-team decision 0255).
+ * `ok: true` names the person whose signature it is (`platform_user_id`, a
+ * `usr_` id) and their sanitized HTML signature, or `html: null` when they set
+ * none. `ok: false` is a refusal; the method never rejects.
+ */
+type SprigrMeSignatureResult = {
+    ok: true;
+    platform_user_id: string;
+    html: string | null;
+} | {
+    ok: false;
+    error: SprigrMeSignatureError;
+    message: string;
+};
+/**
+ * `env.SPRIGR.me`: reads about the PERSON this dispatch acts for. The platform
+ * resolves the person from the signed actor assertion on the dispatch, which
+ * the bridge forwards itself; nothing an app passes can name another person.
+ */
+interface SprigrMeApi {
+    /**
+     * The acting person's Inbox email signature for `channel` (the mail channel
+     * slug, e.g. `'outlook_mail'` or `'google_mail'`): their override for that
+     * channel's family if they set one, else their default. Append it only when
+     * `platform_user_id` owns the mailbox you are sending from (never from a
+     * shared mailbox), and skip it when the body already contains it.
+     * Resolves `no_person` when nobody is acting (a webhook, an agent with no
+     * person behind it, a member who left). Never rejects.
+     */
+    signature(input: {
+        channel: string;
+    }): Promise<SprigrMeSignatureResult>;
+}
 /**
  * Durable app file storage exposed on `env.SPRIGR.files` by the platform
  * wrapper (the platform build-runner). Persists bytes into the install's
@@ -3774,4 +3925,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 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 PublicBaseUrlEnv, 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 SprigrAssertionMintResult, type SprigrAssertionsApi, 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 SprigrDataWriteTimeoutOpts, 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, emailBodyHtml, emailPreview, emitMarketplaceEvent, encodeState, encodeStateWithinEnvelope, fetchFileAsBase64, fetchFileBytes, fetchWithRetry, fieldsPreview, fullWarning, getAppFile, getCompanyTimezone, hasHtmlMarkup, hmacSha256Hex, installTokenPost, isNotConnectedError, isStagingHost, listAppFiles, logToPlatform, makeDataClient, manifestIsFresh, oauthStateEnvelopeOverhead, offerUndo, openFileRef, overlaySprigr, ownerFromActorKey, parseActor, parseActorRetiredArgs, partialUpdateData, publicBaseUrl, 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 };
+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_REPORT_TIMEOUT_MS, 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 PublicBaseUrlEnv, type PurgeResult, type PutAppFileArgs, type PutAppFileResult, type PutAppFileStreamArgs, type ReadFileRefOptions, type ReportToPlatformOptions, 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, SPRIGR_REPORT_LIMITS, SPRIGR_REPORT_SEVERITIES, type ScheduleArgs, type SmsPreviewInput, type SprigrAssertionMintResult, type SprigrAssertionsApi, 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 SprigrDataWriteTimeoutOpts, 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 SprigrMeApi, type SprigrMeSignatureError, type SprigrMeSignatureResult, type SprigrReportFn, type SprigrReportInput, type SprigrReportResult, type SprigrReportSeverity, 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, canReport, checkConfirmationPolicy, commonDestructiveVerbs, connectComplete, connectDisconnect, constantTimeEqual, createMarketplaceEmitter, createToolWrappers, decodeState, defineInboxSendHandler, deleteAppFile, deleteSnapshotIds, deriveConfirmationPolicy, describeMissingBridge, dispatcherApproval, emailBodyHtml, emailPreview, emitMarketplaceEvent, encodeState, encodeStateWithinEnvelope, fetchFileAsBase64, fetchFileBytes, fetchWithRetry, fieldsPreview, fullWarning, getAppFile, getCompanyTimezone, hasHtmlMarkup, hmacSha256Hex, installTokenPost, isNotConnectedError, isStagingHost, listAppFiles, logToPlatform, makeDataClient, manifestIsFresh, oauthStateEnvelopeOverhead, offerUndo, openFileRef, overlaySprigr, ownerFromActorKey, parseActor, parseActorRetiredArgs, partialUpdateData, publicBaseUrl, purgeIndexByPrefix, putAppFile, putAppFileStream, randomHex, readFileRef, readableStoredKey, recreatedWarning, refuseWithoutForce, reportToPlatform, requireApproval, resolveFileRef, resolveInstallBridge, resolveOAuthBouncerBase, resolveOAuthBouncerCallbackUrl, resolvePlatformWebhookBase, resolveViewerContext, resolveViewerUserId, runUndoApply, safeCapture, seq, serializeManifest, set, smsPreview, snapshotIndexIds, tool, undoEnvelope, validateLogEntries, validateLogEntry, verifyViewerToken, withSenderSignature, withSprigrEmitFallback, withSprigrInboxFallback, withSprigrLogFallback };

package/dist/index.js

@@ -960,6 +960,73 @@ function withSprigrLogFallback(env, opts) {
   return overlaySprigr(env, { ...existing, log });
 }
 
+// src/platform-report.ts
+var SPRIGR_REPORT_SEVERITIES = ["low", "medium", "high", "critical"];
+var SPRIGR_REPORT_LIMITS = Object.freeze({
+  keyPattern: /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/,
+  maxTitleChars: 200,
+  maxDetailChars: 8e3,
+  defaultTtlSeconds: 24 * 3600,
+  minTtlSeconds: 3600,
+  maxTtlSeconds: 7 * 24 * 3600,
+  capPerInstallPerDay: 5,
+  capPerAppPerHour: 20
+});
+var DEFAULT_REPORT_TIMEOUT_MS = 5e3;
+function bindingReport(env) {
+  const sprigr = env.SPRIGR;
+  return typeof sprigr?.report === "function" ? sprigr.report.bind(sprigr) : null;
+}
+function canReport(env) {
+  return bindingReport(env) !== null || resolveInstallBridge(env) !== null;
+}
+function failed(err) {
+  return { ok: false, error: "report_failed", detail: err instanceof Error ? err.message : String(err) };
+}
+async function postReport(env, input, timeoutMs) {
+  const bridge = resolveInstallBridge(env);
+  if (!bridge) {
+    return { ok: false, error: "bindings_not_configured", detail: describeMissingBridge(env) };
+  }
+  try {
+    const reply = await installTokenPost(bridge, "/internal/wfp/report", input ?? {}, { label: "report", timeoutMs });
+    if (reply.ok === true && (reply.status === "filed" || reply.status === "deduped" || reply.status === "rate_limited")) {
+      return { ok: true, status: reply.status };
+    }
+    if (reply.ok === false && reply.status === "failed") return { ok: false, status: "failed" };
+    return {
+      ok: false,
+      error: typeof reply.error === "string" ? reply.error : "report_failed",
+      ...typeof reply.detail === "string" ? { detail: reply.detail } : {}
+    };
+  } catch (err) {
+    const e = err;
+    const message2 = e instanceof Error ? e.message : String(err);
+    console.warn(`[sprigr-report] report fallback failed: ${message2}`);
+    return {
+      ok: false,
+      error: e.error ?? (e.status !== void 0 ? "report_failed" : "report_transport_failed"),
+      ...e.status !== void 0 ? { status: e.status } : {},
+      detail: e.detail ?? message2
+    };
+  }
+}
+function reportToPlatform(env, input, opts) {
+  const injected = bindingReport(env);
+  let result;
+  if (injected) {
+    try {
+      result = Promise.resolve(injected(input)).catch(failed);
+    } catch (err) {
+      result = Promise.resolve(failed(err));
+    }
+  } else {
+    result = postReport(env, input, opts?.timeoutMs ?? DEFAULT_REPORT_TIMEOUT_MS);
+  }
+  if (opts?.waitUntil) opts.waitUntil(result);
+  return result;
+}
+
 // src/platform-data.ts
 var DATA_PARTIAL_UPDATE_PATH = "/internal/wfp/data/partial-update";
 var SPRIGR_DATA_MAX_OBJECTS_PER_CALL = 1e3;
@@ -2318,6 +2385,22 @@ function emailBodyHtml(body) {
   if (normalized.length === 0) return body;
   return normalized.split(/\n[ \t]*\n+/).map((para) => `<p>${escapeHtml(para.replace(/^\n+|\n+$/g, "")).replace(/\n/g, "<br>")}</p>`).join("");
 }
+
+// src/sender-signature.ts
+async function withSenderSignature(sprigr, args) {
+  const me = sprigr?.me;
+  if (!args.senderPlatformUserId || typeof me?.signature !== "function") return args.html;
+  try {
+    const sig = await me.signature({ channel: args.channel });
+    if (!sig.ok || !sig.html) return args.html;
+    if (sig.platform_user_id !== args.senderPlatformUserId) return args.html;
+    if (args.html.includes(sig.html)) return args.html;
+    return `${args.html}<br><br>-- <br>${sig.html}`;
+  } catch (err) {
+    console.warn("[app-sdk] env.SPRIGR.me.signature failed; sending without a signature:", err instanceof Error ? err.message : err);
+    return args.html;
+  }
+}
 export {
   ACTOR_RETIRED_HOOK_TOOL,
   ACTOR_RETIRE_REASONS,
@@ -2332,6 +2415,7 @@ export {
   DEFAULT_LOG_TIMEOUT_MS,
   DEFAULT_MAX_FILE_BYTES,
   DEFAULT_MONEY_FIELDS,
+  DEFAULT_REPORT_TIMEOUT_MS,
   DEFAULT_WRITE_PREFIXES,
   FILE_REF_SOURCES_HELP,
   FileRefError,
@@ -2344,6 +2428,8 @@ export {
   SPRIGR_FILE_HOSTS,
   SPRIGR_LOG_LEVELS,
   SPRIGR_LOG_LIMITS,
+  SPRIGR_REPORT_LIMITS,
+  SPRIGR_REPORT_SEVERITIES,
   SprigrDataValidationError,
   SprigrLogValidationError,
   UNIT_SEP,
@@ -2374,6 +2460,7 @@ export {
   canEmit,
   canLog,
   canPartialUpdate,
+  canReport,
   checkConfirmationPolicy,
   commonDestructiveVerbs,
   connectComplete,
@@ -2426,6 +2513,7 @@ export {
   readableStoredKey,
   recreatedWarning,
   refuseWithoutForce,
+  reportToPlatform,
   requireApproval,
   resolveFileRef,
   resolveInstallBridge,
@@ -2446,6 +2534,7 @@ export {
   validateLogEntries,
   validateLogEntry,
   verifyViewerToken,
+  withSenderSignature,
   withSprigrEmitFallback,
   withSprigrInboxFallback,
   withSprigrLogFallback

package/package.json

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