@capxul/sdk 4.20.0-beta.3 → 4.20.0-beta.31

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,3141 +0,0 @@
1
- import { $ as PayrollGroupId, A as AllowanceKey, B as ChainId, C as AuthCachePort, D as Account$1, Et as FailureMode, F as AssetId, H as CurrencyCode, I as AuthSession, K as Email, L as AuthUserId, M as AnonymousDistinctId, N as AppId, Q as PaymentCommandId, R as BlockNumber, U as DocumentHash, V as CountryCode, W as DurationMs, X as OrgId, Y as Money, Z as PartyId, _ as Session$1, _t as CapxulErrorCode, at as RoleKey, b as AuthClientPort, bt as Failure, ct as TesterKind, d as AccountRequirement, et as PayrollRunId, g as Profile$1, gt as CapxulError, h as CapxulResult, i as CapxulSigner, it as PublishableKey, j as AllowedOrigin, k as Address$1, lt as TxHash, nt as PermissionId, ot as SessionToken, q as EpochMs, rt as Profile, s as SignerStatusStore, st as SmartAccount, tt as PermissionAssignmentId, u as AccountProviderSource, ut as WeiAmount, v as SmartAccount$1, vt as CapxulErrorDetails, x as CanSendOtpStatus, y as ClockPort, z as BudgetId } from "./OAuthBearerAuthClient-C-ip-z8M.mjs";
2
- import { Hex } from "viem";
3
- import { Context, Duration, Effect, Layer, Logger, Metric, References, Schema, Scope, Tracer } from "effect";
4
- import { FunctionReference } from "convex/server";
5
- import { HttpClient, HttpClientError } from "effect/unstable/http";
6
- import { OtlpExporter, OtlpSerialization } from "effect/unstable/observability";
7
- //#region src/domain/machine/shell.d.ts
8
- declare const INVOCATION_PARENT_SPAN: unique symbol;
9
- interface InvocationControls {
10
- readonly signal?: AbortSignal;
11
- readonly timeoutMs?: number;
12
- readonly deadlineMs?: number;
13
- readonly correlation_id?: string;
14
- readonly journey_id?: string;
15
- /** @internal Opaque in-process trace parent; symbols never enter wire or P3 records. */
16
- readonly [INVOCATION_PARENT_SPAN]?: Tracer.AnySpan;
17
- }
18
- type RecordBase = {
19
- readonly machine: string;
20
- readonly event: string;
21
- readonly slot: string;
22
- readonly epoch: number;
23
- readonly duration_ms: number;
24
- readonly correlation_id?: string;
25
- readonly journey_id?: string;
26
- };
27
- type IdentityTransition = (RecordBase & {
28
- readonly outcome: "applied";
29
- readonly from: string;
30
- readonly to: string;
31
- readonly refusal_code?: never;
32
- readonly error_code?: never;
33
- }) | (RecordBase & {
34
- readonly outcome: "refused";
35
- readonly state: string;
36
- readonly refusal_code: CapxulErrorCode;
37
- readonly error_code?: never;
38
- }) | (RecordBase & {
39
- readonly outcome: "failed" | "cancelled";
40
- readonly state: string;
41
- readonly error_code: CapxulErrorCode;
42
- readonly refusal_code?: never;
43
- /** The typed failure behind `error_code`, with its `CapxulError` when the port gave one. */
44
- readonly failure?: Failure;
45
- });
46
- declare class ActorFailure<Reason extends CapxulErrorCode> extends Error {
47
- readonly reason: Reason;
48
- readonly machine: string;
49
- readonly state: string;
50
- readonly event: string;
51
- readonly details?: Readonly<Record<string, unknown>> | undefined;
52
- readonly _tag = "ActorFailure";
53
- constructor(reason: Reason, machine: string, state: string, event: string, details?: Readonly<Record<string, unknown>> | undefined, cause?: unknown);
54
- }
55
- interface Actor<S, Pub, Reason extends CapxulErrorCode> {
56
- readonly ask: (event: Pub, controls?: InvocationControls) => Effect.Effect<S, ActorFailure<Reason | CapxulErrorCode>>;
57
- readonly tell: (event: Pub, controls?: InvocationControls) => Effect.Effect<void, ActorFailure<Reason | CapxulErrorCode>>;
58
- readonly snapshot: () => S;
59
- readonly subscribe: (observer: (state: S) => void) => () => void;
60
- readonly subscribeTransitions: (observer: (record: IdentityTransition) => void) => () => void;
61
- }
62
- //#endregion
63
- //#region src/domain/identity/model.d.ts
64
- type RefusalReason = "WRONG_STATE" | "INVALID_INPUT" | "OTP_EXPIRED" | "SIGNER_REJECTED";
65
- interface Session {
66
- readonly email: string;
67
- readonly authUserId: string;
68
- }
69
- /** The initial account state is counterfactual
70
- * and signerless; `deploy` is the separate claim step that needs a signer. */
71
- type AccountStep = "wallet" | "identity" | "provision" | "deploy";
72
- /** org-lifecycle.ts:7-11, verbatim. */
73
- type OrgStep = "preparingFounderAccount" | "awaitingFounderAuthorization" | "submittingBootstrap" | "confirmingBootstrap";
74
- interface OrgDraft {
75
- readonly name: string;
76
- readonly handle: string;
77
- readonly country: string;
78
- }
79
- /** Full one-shot coordinator input. Only {@link OrgDraft} is retained in IdentityState. */
80
- interface OrgSubmissionDraft extends OrgDraft {
81
- readonly bio?: string;
82
- readonly size?: string;
83
- /**
84
- * #1955: the logo uploaded on file pick. The org lane spreads this draft
85
- * straight into `startOrResume`, which records it on the `orgs` insert.
86
- */
87
- readonly logoStorageId?: string;
88
- }
89
- /** The org lane, keyed by the active orgId — which does not exist yet while the
90
- * FIRST DURABLE ORG WRITE is in flight, hence `creating` carrying only a draft. */
91
- type OrgLane = {
92
- readonly at: "creating";
93
- readonly draft: OrgDraft;
94
- } | {
95
- readonly at: "loading";
96
- readonly orgId: string;
97
- } | {
98
- readonly at: "settingUp";
99
- readonly orgId: string;
100
- readonly step: OrgStep;
101
- } | {
102
- readonly at: "ready";
103
- readonly orgId: string;
104
- } | {
105
- readonly at: "failed";
106
- readonly orgId: string | null;
107
- readonly step: OrgStep;
108
- readonly failure: Failure;
109
- readonly retryable: boolean;
110
- };
111
- /**
112
- * Personal-account readiness — the ONLY pre-org readiness truth (#1049 #1051).
113
- * `claimed` is the single variant with an `org` field: the map's ordering
114
- * `Account deployed+claimed → first durable Organization write` is expressed by
115
- * the absence of that field everywhere else, not by a guard someone can forget.
116
- */
117
- type Readiness = {
118
- readonly at: "unknown";
119
- } | {
120
- readonly at: "deriving";
121
- readonly step: AccountStep;
122
- } | {
123
- readonly at: "counterfactual";
124
- readonly address: string;
125
- } | {
126
- readonly at: "claiming";
127
- readonly address: string;
128
- } | {
129
- readonly at: "claimed";
130
- readonly address: string;
131
- readonly org: OrgLane | null;
132
- } | {
133
- readonly at: "failed";
134
- readonly step: AccountStep;
135
- readonly failure: Failure;
136
- readonly retryable: boolean;
137
- };
138
- type IdentityState =
139
- /** The INITIAL state: a session probe is in flight and the machine knows
140
- * nothing yet. Distinct from `signed_out`, which is a settled answer. Without
141
- * it every consumer read the restore window as a real sign-out. */
142
- {
143
- readonly phase: "restoring";
144
- } | {
145
- readonly phase: "signed_out";
146
- } | {
147
- readonly phase: "otp_sending";
148
- readonly email: string;
149
- } | {
150
- readonly phase: "otp_pending";
151
- readonly email: string;
152
- readonly requestedAt: number;
153
- } | {
154
- readonly phase: "otp_verifying";
155
- readonly email: string;
156
- readonly requestedAt: number;
157
- } | {
158
- readonly phase: "authenticated";
159
- readonly session: Session;
160
- readonly profileComplete: boolean;
161
- readonly account: Readiness;
162
- } | {
163
- readonly phase: "signing_out";
164
- readonly session: Session | null;
165
- } | {
166
- readonly phase: "faulted";
167
- readonly failure: Failure;
168
- /** Non-null exactly when an OTP entry is resumable — the incumbent's
169
- * `email !== null && otpRequestedAt !== null` pair,
170
- * made structural. */
171
- readonly resume: {
172
- readonly email: string;
173
- readonly requestedAt: number;
174
- } | null;
175
- };
176
- declare const STATE_LABELS: readonly ["restoring", "signed_out", "otp_sending", "otp_pending", "otp_verifying", "authenticated:unknown", "authenticated:deriving", "authenticated:counterfactual", "authenticated:claiming", "authenticated:failed", "authenticated:claimed", "authenticated:claimed:creating", "authenticated:claimed:loading", "authenticated:claimed:settingUp", "authenticated:claimed:ready", "authenticated:claimed:failed", "signing_out", "faulted"];
177
- type StateLabel = (typeof STATE_LABELS)[number];
178
- type IdentityEvent = {
179
- readonly _tag: "RequestOtp";
180
- readonly email: string;
181
- } | {
182
- readonly _tag: "VerifyOtp";
183
- readonly email: string;
184
- readonly otp: string;
185
- readonly now: number;
186
- } | {
187
- readonly _tag: "ReadSession";
188
- } | {
189
- readonly _tag: "SignOut";
190
- } | {
191
- readonly _tag: "RestoreSession";
192
- readonly session: Session;
193
- readonly profileComplete: boolean;
194
- } | {
195
- readonly _tag: "ResumeOtpEntry";
196
- readonly now: number;
197
- } | {
198
- readonly _tag: "Reset";
199
- } | {
200
- readonly _tag: "SessionRestored";
201
- readonly session: Session;
202
- readonly profileComplete: boolean;
203
- } | {
204
- readonly _tag: "SessionAbsent";
205
- } | {
206
- readonly _tag: "EnsureAccount";
207
- } | {
208
- readonly _tag: "ClaimAccount";
209
- } | {
210
- readonly _tag: "RetryAccount";
211
- } | {
212
- readonly _tag: "CreateOrganization";
213
- readonly draft: OrgSubmissionDraft;
214
- } | {
215
- readonly _tag: "AttachOrganization";
216
- readonly orgId: string;
217
- } | {
218
- readonly _tag: "RetryOrganization";
219
- } | {
220
- readonly _tag: "LeaveOrganization";
221
- };
222
- type Destination$1 = {
223
- readonly to: "home";
224
- } | {
225
- readonly to: "selectUserType";
226
- } | {
227
- readonly to: "provisioning";
228
- readonly scope: "personal";
229
- } | {
230
- readonly to: "provisioning";
231
- readonly scope: "organization";
232
- readonly orgId: string | null;
233
- } | {
234
- readonly to: "dashboardPersonal";
235
- } | {
236
- readonly to: "dashboardOrganization";
237
- readonly orgId: string;
238
- };
239
- /**
240
- * The post-auth destination and provisioning lane merge as one total switch
241
- * over the nest. "An active journey outranks default
242
- * routing; org-list contents never choose a destination" holds by construction:
243
- * there is no org list in the state, only the ONE active lane.
244
- */
245
- declare const destination: (state: IdentityState) => Destination$1 | null;
246
- /**
247
- * True while the machine has not settled enough to route or to gate on.
248
- *
249
- * NEGATIVE classification, deliberately: the SETTLED positions are the ones
250
- * enumerated, and everything else waits. A phase or readiness variant added
251
- * later therefore defaults to holding, never to redirecting a member who is in
252
- * fact signed in. Terminal for the account lane is `claimed | failed`.
253
- *
254
- * The org lane's own settledness (`ready | failed`) is the route gate's
255
- * question, not this one: every org lane sits under a CLAIMED account, and
256
- * `destination()` already names a real screen for each of its positions.
257
- */
258
- declare const isRestoring: (state: IdentityState) => boolean;
259
- /** The claimed-account gate as one function. The inlined consumers move onto
260
- * it in #1521; this ticket ships the selector they move onto. */
261
- declare const isClaimed: (state: IdentityState) => boolean;
262
- //#endregion
263
- //#region ../observability/src/telemetry-port.d.ts
264
- /**
265
- * Context for reporting handled errors via `reportHandledError`.
266
- * Carries structured metadata extracted from the error context.
267
- */
268
- interface HandledErrorReportContext {
269
- readonly layer?: string;
270
- /** Host input is normalized at the reporting boundary. */
271
- readonly operation?: string;
272
- readonly failure_mode?: FailureMode;
273
- readonly provider?: string;
274
- }
275
- /**
276
- * Canonical TelemetryPort interface. Every adapter (production, test, in-memory)
277
- * implements this contract. All methods return `Effect<void, never>` —
278
- * fire-and-forget, defects are caught and traced.
279
- */
280
- interface TelemetryPort {
281
- readonly emit: (event: TelemetryEvent) => Effect.Effect<void, never>;
282
- readonly identify: (input: TelemetryIdentifyInput) => Effect.Effect<void, never>;
283
- readonly group: (input: TelemetryGroupInput) => Effect.Effect<void, never>;
284
- readonly reset: () => Effect.Effect<void, never>;
285
- readonly reportHandledError?: (error: CapxulError, context?: HandledErrorReportContext) => Effect.Effect<void, never>;
286
- }
287
- //#endregion
288
- //#region ../observability/src/index.d.ts
289
- declare const TELEMETRY_EVENT_NAMES: readonly ["auth_otp_requested", "auth_otp_delivered", "auth_otp_expired", "auth_verified", "auth_failed", "identity_refused", "auth_signed_out", "onboarding_intent_selected", "onboarding_profile_submitted", "onboarding_organization_submitted", "onboarding_dashboard_reached", "provisioning_safe_created", "provisioning_safe_confirmed", "bootstrap_resolved", "bootstrap_failed", "member_activation_started", "member_activation_ready", "member_activation_failed", "organization_creation_started", "organization_creation_ready", "organization_creation_failed", "chain_upstream_fallback", "bundler_error", "receipt_pending", "operation_retried", "account_balance_read", "account_balance_failed", "faucet_requested", "faucet_confirmed", "faucet_failed", "org_create_started", "org_safe_created", "org_safe_confirmed", "org_roles_seeded", "org_created", "org_create_failed", "org_invite_sent", "org_invite_accepted", "org_invite_expired", "payment_initiated", "payment_settled", "payment_failed", "payment_verification_retry", "payment_lifecycle_transition", "quick_pay_external_address_acknowledged", "deposit_initiated", "deposit_settled", "permission_mirror_verification", "movement_scan_window", "movement_scan_checkpoint", "movement_scan_incident", "indexer_drift_corrected", "activity_annotation_saved", "ui_activity_action_completed", "contact_relationship_changed", "ui_contact_action_completed", "access_recovery_completed", "ui_access_step_completed", "org_invite_progressed", "invoice_issued", "invoice_request_transitioned", "ui_invoice_step_completed", "ui_treasury_step_completed", "ui_receive_step_completed", "payroll_group_changed", "payroll_run_transitioned", "ui_payroll_action_completed", "cli_diagnostic_completed", "cli_first_used", "cli_command_started", "cli_command_completed"];
290
- type TelemetryEventName = (typeof TELEMETRY_EVENT_NAMES)[number];
291
- type TelemetryProps = Record<string, unknown>;
292
- type TelemetryEvent = {
293
- readonly name: TelemetryEventName;
294
- readonly props?: TelemetryProps | undefined;
295
- };
296
- /**
297
- * Environment discriminator (ADR-0020 A1 amendment, 2026-08-07). PostHog
298
- * project 368736 is the SINGLE sink for every environment, so `capxul_env` —
299
- * not project isolation — is what keeps a production surface from reading dev
300
- * traffic. It is REQUIRED on every catalog event and every synced artifact
301
- * filters on it.
302
- *
303
- * `unknown` is a defect marker, not an environment: it means a producer
304
- * reached the transport without declaring where it runs. It is in the union so
305
- * the property is never ABSENT (an absent property is invisible to a filter,
306
- * a present `unknown` is loud), and sync v2 never synthesizes an artifact for
307
- * it.
308
- */
309
- declare const CAPXUL_ENVS: readonly ["development", "staging", "production", "unknown", "local"];
310
- type CapxulEnv = (typeof CAPXUL_ENVS)[number];
311
- interface TelemetryIdentifyInput {
312
- readonly distinctId: string;
313
- readonly anonDistinctId?: AnonymousDistinctId;
314
- readonly traits?: TelemetryProps;
315
- readonly properties?: TelemetryProps;
316
- }
317
- interface TelemetryGroupInput {
318
- readonly groupType: string;
319
- readonly groupKey: string;
320
- readonly properties?: TelemetryProps;
321
- }
322
- //#endregion
323
- //#region ../wire/src/bootstrap.d.ts
324
- declare const EngineeringTelemetryBootstrapPolicy: Schema.Struct<{
325
- readonly host: Schema.refine<string, Schema.String>;
326
- readonly projectToken: Schema.refine<string, Schema.String>;
327
- readonly capxulEnv: Schema.Union<readonly [Schema.Literal<"development">, Schema.Literal<"staging">, Schema.Literal<"production">, Schema.Literal<"local">]>;
328
- }>;
329
- type EngineeringTelemetryBootstrapPolicyV1 = Schema.Schema.Type<typeof EngineeringTelemetryBootstrapPolicy>;
330
- //#endregion
331
- //#region ../wire/src/status.d.ts
332
- /** The closed Payment status authority. */
333
- declare const PAYMENT_STATUSES: readonly ["pending", "settling", "unresolved", "scheduled", "streaming", "pending_claim", "settled", "cancelled", "failed"];
334
- type PaymentStatus$1 = (typeof PAYMENT_STATUSES)[number];
335
- declare const PAYMENT_EXECUTION_STATUSES: readonly ["pending", "included", "dropped", "replaced", "expired", "unresolved", "superseded", "failed", "settled"];
336
- type PaymentExecutionStatus = (typeof PAYMENT_EXECUTION_STATUSES)[number];
337
- /** Read-time execution meaning; it does not change the Payment's durable outcome. */
338
- interface PaymentExecutionView {
339
- readonly status: PaymentExecutionStatus;
340
- readonly retryRequired: boolean;
341
- /** Present only when complete durable execution history supports no broadcast. */
342
- readonly notSent?: true;
343
- }
344
- /** The payment direction relative to the current actor. */
345
- declare const PAYMENT_DIRECTIONS: readonly ["in", "out", "self"];
346
- type PaymentDirection$1 = (typeof PAYMENT_DIRECTIONS)[number];
347
- /** What a payment is FOR. Pairs with `PAYMENT_DOCUMENT_KINDS`. */
348
- declare const PAYMENT_TYPES: readonly ["unspecified", "invoice", "payroll", "reimbursement"];
349
- type PaymentType$1 = (typeof PAYMENT_TYPES)[number];
350
- /** Attachable document kinds; each maps to exactly one `PaymentType`. */
351
- declare const PAYMENT_DOCUMENT_KINDS: readonly ["memo", "invoice", "payslip", "receipt", "withdrawal"];
352
- type PaymentDocumentKind$1 = (typeof PAYMENT_DOCUMENT_KINDS)[number];
353
- /** Lifecycle of a payment REQUEST as its issuer sees it. */
354
- declare const REQUEST_STATUSES: readonly ["draft", "sent", "viewed", "pending_settlement", "paid", "declined", "cancelled", "expired"];
355
- type RequestStatus = (typeof REQUEST_STATUSES)[number];
356
- /** The same request as its RECIPIENT sees it, in the approval inbox. */
357
- declare const INBOX_STATUSES: readonly ["open", "approved", "declined", "paid", "cancelled", "expired"];
358
- type InboxStatus = (typeof INBOX_STATUSES)[number];
359
- //#endregion
360
- //#region ../wire/src/financial-ops.d.ts
361
- declare const AttachablePaymentDocumentEnvelope: Schema.Union<readonly [Schema.Struct<{
362
- readonly protocol: Schema.Literal<"capxul.payment-document">;
363
- readonly version: Schema.Literal<1>;
364
- readonly domain: Schema.Struct<{
365
- readonly name: Schema.Literal<"CapxulPayments">;
366
- readonly version: Schema.Literal<"1">;
367
- readonly chainId: Schema.Codec<ChainId, number, never, never>;
368
- readonly verifyingContract: Schema.Literal<"0x7a5c25aB7ce91d7a475B71cd1ec33E230291f8a4">;
369
- }>;
370
- readonly primaryType: Schema.Literal<"Memo">;
371
- readonly message: Schema.Struct<{
372
- readonly kind: Schema.Literal<0>;
373
- readonly reference: Schema.String;
374
- readonly note: Schema.String;
375
- readonly issuedAt: Schema.Number;
376
- }>;
377
- }>, Schema.Struct<{
378
- readonly protocol: Schema.Literal<"capxul.payment-document">;
379
- readonly version: Schema.Literal<1>;
380
- readonly domain: Schema.Struct<{
381
- readonly name: Schema.Literal<"CapxulPayments">;
382
- readonly version: Schema.Literal<"1">;
383
- readonly chainId: Schema.Codec<ChainId, number, never, never>;
384
- readonly verifyingContract: Schema.Literal<"0x7a5c25aB7ce91d7a475B71cd1ec33E230291f8a4">;
385
- }>;
386
- readonly primaryType: Schema.Literal<"Invoice">;
387
- readonly message: Schema.Struct<{
388
- readonly kind: Schema.Literal<1>;
389
- readonly invoiceNumber: Schema.String;
390
- readonly payerRef: Schema.String;
391
- readonly payeeRef: Schema.String;
392
- readonly amount: Schema.String;
393
- readonly currency: Schema.Codec<CurrencyCode, string, never, never>;
394
- readonly decimals: Schema.Number;
395
- readonly issuedAt: Schema.Number;
396
- readonly dueAt: Schema.Number;
397
- readonly lineItemsHash: Schema.Codec<DocumentHash, string, never, never>;
398
- }>;
399
- }>, Schema.Struct<{
400
- readonly protocol: Schema.Literal<"capxul.payment-document">;
401
- readonly version: Schema.Literal<1>;
402
- readonly domain: Schema.Struct<{
403
- readonly name: Schema.Literal<"CapxulPayments">;
404
- readonly version: Schema.Literal<"1">;
405
- readonly chainId: Schema.Codec<ChainId, number, never, never>;
406
- readonly verifyingContract: Schema.Literal<"0x7a5c25aB7ce91d7a475B71cd1ec33E230291f8a4">;
407
- }>;
408
- readonly primaryType: Schema.Literal<"Payslip">;
409
- readonly message: Schema.Struct<{
410
- readonly kind: Schema.Literal<2>;
411
- readonly employerRef: Schema.String;
412
- readonly employeeRef: Schema.String;
413
- readonly period: Schema.String;
414
- readonly gross: Schema.String;
415
- readonly net: Schema.String;
416
- readonly currency: Schema.Codec<CurrencyCode, string, never, never>;
417
- readonly decimals: Schema.Number;
418
- readonly issuedAt: Schema.Number;
419
- }>;
420
- }>, Schema.Struct<{
421
- readonly protocol: Schema.Literal<"capxul.payment-document">;
422
- readonly version: Schema.Literal<1>;
423
- readonly domain: Schema.Struct<{
424
- readonly name: Schema.Literal<"CapxulPayments">;
425
- readonly version: Schema.Literal<"1">;
426
- readonly chainId: Schema.Codec<ChainId, number, never, never>;
427
- readonly verifyingContract: Schema.Literal<"0x7a5c25aB7ce91d7a475B71cd1ec33E230291f8a4">;
428
- }>;
429
- readonly primaryType: Schema.Literal<"Receipt">;
430
- readonly message: Schema.Struct<{
431
- readonly kind: Schema.Literal<3>;
432
- readonly reference: Schema.String;
433
- readonly amount: Schema.String;
434
- readonly currency: Schema.Codec<CurrencyCode, string, never, never>;
435
- readonly decimals: Schema.Number;
436
- readonly paidAt: Schema.Number;
437
- readonly note: Schema.String;
438
- }>;
439
- }>]>;
440
- /**
441
- * #592 invoice line item. `quantity` is a positive integer; `unitMinor` is the
442
- * per-unit price in integer minor units. The list is canonically hashed by
443
- * `hashLineItems` (payment-document-hash.ts) into the Invoice `lineItemsHash`,
444
- * and Σ(quantity × unitMinor) MUST equal the invoice `amount`. The hash binds
445
- * the documentHash to the exact items; the sum-check makes the items add up to
446
- * the amount due. See the financial-operations contract in `packages/wire/CONTEXT.md`.
447
- */
448
- declare const LineItem: Schema.Struct<{
449
- readonly description: Schema.String;
450
- readonly quantity: Schema.Number;
451
- readonly unitMinor: Schema.String;
452
- }>;
453
- type AttachablePaymentDocumentEnvelopeV1 = Schema.Schema.Type<typeof AttachablePaymentDocumentEnvelope>;
454
- type LineItemV1 = Schema.Schema.Type<typeof LineItem>;
455
- //#endregion
456
- //#region ../wire/src/money.d.ts
457
- declare const ActorRefSchema: Schema.Union<readonly [Schema.Struct<{
458
- readonly kind: Schema.Literal<"account">;
459
- readonly accountId: Schema.refine<string, Schema.String>;
460
- }>, Schema.Struct<{
461
- readonly kind: Schema.Literal<"organization">;
462
- readonly orgId: Schema.refine<string, Schema.String>;
463
- }>]>;
464
- type ActorRef = Schema.Schema.Type<typeof ActorRefSchema>;
465
- declare const PermissionSchema: Schema.Struct<{
466
- readonly permissionId: Schema.Codec<PermissionId, string, never, never>;
467
- readonly orgId: Schema.refine<string, Schema.String>;
468
- readonly type: Schema.Literals<readonly ["budget", "managePeople"]>;
469
- readonly state: Schema.Literals<readonly ["pending", "active", "suspended", "revoked", "superseded"]>;
470
- readonly revision: Schema.refine<number, Schema.Number>;
471
- readonly roleKey: Schema.Codec<RoleKey, string, never, never>;
472
- readonly tokenAddress: Schema.optional<Schema.Codec<Address$1, string, never, never>>;
473
- readonly limitRaw: Schema.optional<Schema.Codec<WeiAmount, string, never, never>>;
474
- readonly allowanceKey: Schema.optional<Schema.Codec<AllowanceKey, string, never, never>>;
475
- }>;
476
- type Permission = Schema.Schema.Type<typeof PermissionSchema>;
477
- declare const PermissionAssignmentSchema: Schema.Struct<{
478
- readonly permissionAssignmentId: Schema.Codec<PermissionAssignmentId, string, never, never>;
479
- readonly permissionId: Schema.Codec<PermissionId, string, never, never>;
480
- readonly actor: Schema.Union<readonly [Schema.Struct<{
481
- readonly kind: Schema.Literal<"account">;
482
- readonly accountId: Schema.refine<string, Schema.String>;
483
- }>, Schema.Struct<{
484
- readonly kind: Schema.Literal<"organization">;
485
- readonly orgId: Schema.refine<string, Schema.String>;
486
- }>]>;
487
- readonly state: Schema.Literals<readonly ["pending", "active", "suspended", "revoked", "superseded"]>;
488
- }>;
489
- type PermissionAssignment = Schema.Schema.Type<typeof PermissionAssignmentSchema>;
490
- declare const CurrentHoldingsSchema: Schema.Struct<{
491
- readonly actor: Schema.Union<readonly [Schema.Struct<{
492
- readonly kind: Schema.Literal<"account">;
493
- readonly accountId: Schema.refine<string, Schema.String>;
494
- }>, Schema.Struct<{
495
- readonly kind: Schema.Literal<"organization">;
496
- readonly orgId: Schema.refine<string, Schema.String>;
497
- }>]>;
498
- readonly chainId: Schema.Codec<ChainId, number, never, never>;
499
- readonly observedAt: Schema.refine<number, Schema.Number>;
500
- readonly stale: Schema.Boolean;
501
- readonly rows: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
502
- readonly assetKind: Schema.Literal<"native">;
503
- readonly symbol: Schema.optional<Schema.String>;
504
- readonly decimals: Schema.optional<Schema.refine<number, Schema.Number>>;
505
- readonly rawBalance: Schema.Codec<WeiAmount, string, never, never>;
506
- }>, Schema.Struct<{
507
- readonly assetKind: Schema.Literal<"erc20">;
508
- readonly tokenAddress: Schema.Codec<Address$1, string, never, never>;
509
- readonly symbol: Schema.optional<Schema.String>;
510
- readonly decimals: Schema.optional<Schema.refine<number, Schema.Number>>;
511
- readonly rawBalance: Schema.Codec<WeiAmount, string, never, never>;
512
- }>]>>;
513
- }>;
514
- type CurrentHoldings = Schema.Schema.Type<typeof CurrentHoldingsSchema>;
515
- declare const PaymentCommandLineageSchema: Schema.Union<readonly [Schema.Struct<{
516
- readonly kind: Schema.Literal<"payroll">;
517
- readonly runId: Schema.refine<string, Schema.String>;
518
- }>, Schema.Struct<{
519
- readonly kind: Schema.Literal<"payment_request">;
520
- readonly requestId: Schema.refine<string, Schema.String>;
521
- }>]>;
522
- type PaymentCommandLineage = Schema.Schema.Type<typeof PaymentCommandLineageSchema>;
523
- declare const PermissionIntentSchema: Schema.Union<readonly [Schema.Struct<{
524
- readonly type: Schema.Literal<"budget">;
525
- readonly limit: Schema.Struct<{
526
- readonly currency: Schema.Codec<CurrencyCode, string, never, never>;
527
- readonly value: Schema.String;
528
- readonly decimals: Schema.Number;
529
- }>;
530
- }>, Schema.Struct<{
531
- readonly type: Schema.Literal<"managePeople">;
532
- }>]>;
533
- type PermissionIntent = Schema.Schema.Type<typeof PermissionIntentSchema>;
534
- declare const SubmittedPermissionExecutionSchema: Schema.Struct<{
535
- readonly status: Schema.Literal<"submitted">;
536
- readonly executionId: Schema.refine<string, Schema.String>;
537
- readonly commandId: Schema.Codec<PaymentCommandId, string, never, never>;
538
- readonly userOpHash: Schema.Codec<string, string, never, never>;
539
- readonly value: Schema.Union<readonly [Schema.Struct<{
540
- readonly permissionId: Schema.Codec<PermissionId, string, never, never>;
541
- readonly orgId: Schema.refine<string, Schema.String>;
542
- readonly type: Schema.Literals<readonly ["budget", "managePeople"]>;
543
- readonly state: Schema.Literals<readonly ["pending", "active", "suspended", "revoked", "superseded"]>;
544
- readonly revision: Schema.refine<number, Schema.Number>;
545
- readonly roleKey: Schema.Codec<RoleKey, string, never, never>;
546
- readonly tokenAddress: Schema.optional<Schema.Codec<Address$1, string, never, never>>;
547
- readonly limitRaw: Schema.optional<Schema.Codec<WeiAmount, string, never, never>>;
548
- readonly allowanceKey: Schema.optional<Schema.Codec<AllowanceKey, string, never, never>>;
549
- }>, Schema.Struct<{
550
- readonly permissionAssignmentId: Schema.Codec<PermissionAssignmentId, string, never, never>;
551
- readonly permissionId: Schema.Codec<PermissionId, string, never, never>;
552
- readonly actor: Schema.Union<readonly [Schema.Struct<{
553
- readonly kind: Schema.Literal<"account">;
554
- readonly accountId: Schema.refine<string, Schema.String>;
555
- }>, Schema.Struct<{
556
- readonly kind: Schema.Literal<"organization">;
557
- readonly orgId: Schema.refine<string, Schema.String>;
558
- }>]>;
559
- readonly state: Schema.Literals<readonly ["pending", "active", "suspended", "revoked", "superseded"]>;
560
- }>, Schema.$Array<Schema.Struct<{
561
- readonly permissionId: Schema.Codec<PermissionId, string, never, never>;
562
- readonly orgId: Schema.refine<string, Schema.String>;
563
- readonly type: Schema.Literals<readonly ["budget", "managePeople"]>;
564
- readonly state: Schema.Literals<readonly ["pending", "active", "suspended", "revoked", "superseded"]>;
565
- readonly revision: Schema.refine<number, Schema.Number>;
566
- readonly roleKey: Schema.Codec<RoleKey, string, never, never>;
567
- readonly tokenAddress: Schema.optional<Schema.Codec<Address$1, string, never, never>>;
568
- readonly limitRaw: Schema.optional<Schema.Codec<WeiAmount, string, never, never>>;
569
- readonly allowanceKey: Schema.optional<Schema.Codec<AllowanceKey, string, never, never>>;
570
- }>>]>;
571
- }>;
572
- type SubmittedPermissionExecution = Schema.Schema.Type<typeof SubmittedPermissionExecutionSchema>;
573
- declare const PayrollRunStatusSchema: Schema.Literals<readonly ["draft", "authorized", "settled"]>;
574
- type PayrollRunStatus$1 = Schema.Schema.Type<typeof PayrollRunStatusSchema>;
575
- declare const PayrollTermsUnitSchema: Schema.Literals<readonly ["hour", "week", "month", "year", "paycheck"]>;
576
- type PayrollTermsUnit$1 = Schema.Schema.Type<typeof PayrollTermsUnitSchema>;
577
- //#endregion
578
- //#region ../wire/src/observation-context.d.ts
579
- /**
580
- * Bounded, non-authoritative observation metadata carried by selected SDK
581
- * calls. Actor identity is deliberately absent: the backend derives it from
582
- * the authenticated session and verifies organization/application hints.
583
- */
584
- interface WireObservationContext {
585
- readonly application?: string;
586
- readonly applicationId?: string;
587
- readonly release?: string;
588
- readonly sessionId?: string;
589
- readonly organizationId?: string;
590
- readonly journeyId?: string;
591
- readonly correlationId?: string;
592
- readonly anonymousId?: string;
593
- /** W3C trace carrier for the explicit Convex action hop; never product identity. */
594
- readonly traceparent?: string;
595
- }
596
- //#endregion
597
- //#region src/ports/bootstrap.d.ts
598
- type BootstrapInput = {
599
- readonly publishableKey: PublishableKey;
600
- /**
601
- * Browser callers send the App origin so bootstrap can enforce the
602
- * publishable-key allowlist. Node/server callers may omit it; the backend
603
- * only applies the origin allowlist when an origin is present.
604
- */
605
- readonly origin?: AllowedOrigin;
606
- };
607
- type BootstrapResolution = {
608
- readonly applicationId: AppId;
609
- readonly chainId: ChainId;
610
- /**
611
- * SDK-handshake session token — distinct from the user-auth `AuthSession`
612
- * token issued by `AuthClientPort`. Both use the `SessionToken` brand for
613
- * opaque-string discipline; the issuance source distinguishes them.
614
- */
615
- readonly sessionToken: SessionToken;
616
- readonly issuedAt: EpochMs;
617
- readonly expiresIn: DurationMs;
618
- readonly authBaseUrl: string;
619
- readonly convexUrl: string;
620
- readonly siteBaseUrl: string;
621
- readonly openfortPublishableKey: string;
622
- readonly shieldPublishableKey: string;
623
- /** Openfort third-party auth provider the signer presents; absent means better-auth. */
624
- readonly openfortAuthProvider?: "better-auth" | "oidc";
625
- /** Origin of the Ponder indexer the SDK reads directly; absent means no indexer reads. */
626
- readonly indexerUrl?: string;
627
- readonly engineeringTelemetry?: EngineeringTelemetryBootstrapPolicyV1;
628
- };
629
- type BootstrapErrorKind = "notAuthenticated" | "network" | "provider" | "malformedBody" | "invalidInput" | "rateLimited";
630
- declare const BootstrapError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
631
- readonly _tag: "BootstrapError";
632
- } & Readonly<A>;
633
- declare class BootstrapError extends BootstrapError_base<{
634
- readonly operation: "resolve";
635
- readonly kind: BootstrapErrorKind;
636
- readonly publicCode: CapxulErrorCode;
637
- readonly cause: unknown;
638
- readonly details?: CapxulErrorDetails;
639
- }> {}
640
- interface BootstrapPort {
641
- readonly resolve: (input: BootstrapInput) => Effect.Effect<BootstrapResolution, BootstrapError>;
642
- }
643
- //#endregion
644
- //#region src/ports/convex-call.d.ts
645
- /**
646
- * Canonical teardown handle for substrate-level reactive callbacks.
647
- *
648
- * Calling it stops the subscription; no further snapshots will be delivered
649
- * to the callback after the first invocation. Calling more than once is a
650
- * no-op (idempotent).
651
- *
652
- * @internal-use
653
- */
654
- type Unsubscribe = () => void;
655
- /**
656
- * Snapshot is the substrate discriminated union for reactive callbacks over
657
- * `ConvexCallPort.subscribe`. The public SDK surface is imperative
658
- * (`Promise<CapxulResult>`).
659
- *
660
- * - `loading` · initial state before any value arrives from the substrate
661
- * - `ok` · a successful snapshot carrying `value`
662
- * - `error` · a failed snapshot carrying a typed error (defaults to
663
- * `CapxulError`)
664
- *
665
- * The first snapshot is `loading`. Later snapshots carry `ok` or `error`.
666
- *
667
- * Domain ports do not expose reactive callback methods. `ConvexCallPort` owns
668
- * the `subscribe` method.
669
- *
670
- * @internal-use
671
- */
672
- type Snapshot<T, E = CapxulError> = {
673
- readonly status: "loading";
674
- } | {
675
- readonly status: "ok";
676
- readonly value: T;
677
- } | {
678
- readonly status: "error";
679
- readonly error: E;
680
- };
681
- type ConvexTransportFailure = {
682
- readonly kind: "connection-lost-in-flight";
683
- readonly connection_id: string;
684
- readonly start_connection_count: number;
685
- readonly connection_count: number;
686
- readonly connection_retries?: number;
687
- readonly close_code?: number;
688
- readonly close_was_clean?: boolean;
689
- readonly close_reason_present?: boolean;
690
- readonly document_visibility?: string;
691
- readonly navigator_online?: boolean;
692
- readonly last_browser_event?: "visibility-visible" | "visibility-hidden" | "pagehide" | "pageshow" | "online" | "offline";
693
- readonly ms_since_browser_event?: number;
694
- };
695
- declare const ConvexCallError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
696
- readonly _tag: "ConvexCallError";
697
- } & Readonly<A>;
698
- declare class ConvexCallError extends ConvexCallError_base<{
699
- readonly operation: string;
700
- readonly publicCode: CapxulErrorCode;
701
- readonly publicError: CapxulError;
702
- readonly cause: unknown;
703
- readonly details?: CapxulErrorDetails;
704
- readonly transport?: ConvexTransportFailure;
705
- }> {}
706
- interface ConvexCallPort {
707
- query<TArgs extends Record<string, unknown>, TOutput>(fn: FunctionReference<"query", "public", TArgs, TOutput>, args: TArgs): Effect.Effect<TOutput, ConvexCallError>;
708
- mutation<TArgs extends Record<string, unknown>, TOutput>(fn: FunctionReference<"mutation", "public", TArgs, TOutput>, args: TArgs): Effect.Effect<TOutput, ConvexCallError>;
709
- action<TArgs extends Record<string, unknown>, TOutput>(fn: FunctionReference<"action", "public", TArgs, TOutput>, args: TArgs): Effect.Effect<TOutput, ConvexCallError>;
710
- /**
711
- * Substrate-level reactive transport over Convex's `onUpdate`.
712
- *
713
- * @internal-use — substrate only; see `ports/subscription.ts`. Domain
714
- * ports do not expose reactive callback methods to consumers.
715
- */
716
- subscribe<TArgs extends Record<string, unknown>, TOutput>(fn: FunctionReference<"query", "public", TArgs, TOutput>, args: TArgs, callback: (snapshot: Snapshot<TOutput>) => void): Effect.Effect<Unsubscribe, ConvexCallError>;
717
- }
718
- //#endregion
719
- //#region src/ports/identity.d.ts
720
- type CreateIdentityInput = {
721
- readonly authUserId: AuthUserId;
722
- readonly email: Email;
723
- readonly displayName?: string;
724
- readonly country?: CountryCode;
725
- };
726
- type UpdateIdentityInput = {
727
- readonly authUserId: AuthUserId;
728
- readonly displayName?: string;
729
- readonly country?: CountryCode;
730
- };
731
- /** The chain families a payout address may name (#1955). */
732
- declare const PAYOUT_CHAINS: readonly ["evm", "solana", "starknet"];
733
- /**
734
- * One payout address, named BY CHAIN FAMILY. The network is the deployment's
735
- * and the backend derives it (#1955) — a caller never sends one.
736
- */
737
- type PayoutAddress = {
738
- readonly chain: (typeof PAYOUT_CHAINS)[number];
739
- readonly address: string;
740
- };
741
- /**
742
- * D-ONBOARD (#669) — the onboarding-complete identity write. Composes the
743
- * existing create/update write into one idempotent upsert that ALSO sets the
744
- * `onboarded` flag and persists the optional `withdrawalAddress` (the one
745
- * allowed raw-0x class). `displayName` + `country` are required at onboarding
746
- * time. The returned `Profile` is the existing branded shape — the onboarding
747
- * flags live on the wire row and are not projected onto the read surface.
748
- *
749
- * #1955: it also carries the photo the signup form uploaded and the payout
750
- * addresses it collected, so the backend writes all three in one transaction
751
- * instead of the app binding them with two more calls afterwards.
752
- */
753
- type CompleteOnboardingIdentityInput = {
754
- readonly authUserId: AuthUserId;
755
- readonly email: Email;
756
- readonly displayName: string;
757
- readonly country: CountryCode;
758
- readonly withdrawalAddress?: Address$1;
759
- /** One globally unique Party handle. */
760
- readonly handle: string;
761
- /** Storage id from `media.uploadImage`; bound on the identity write itself. */
762
- readonly imageStorageId?: string;
763
- readonly payoutAddresses?: readonly PayoutAddress[];
764
- };
765
- declare const IdentityError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
766
- readonly _tag: "IdentityError";
767
- } & Readonly<A>;
768
- declare class IdentityError extends IdentityError_base<{
769
- readonly operation: string;
770
- readonly publicCode: CapxulErrorCode;
771
- readonly publicError: CapxulError;
772
- readonly cause: unknown;
773
- readonly details?: CapxulErrorDetails;
774
- }> {}
775
- interface IdentityPort {
776
- loadByAuthUserId(authUserId: AuthUserId): Effect.Effect<Profile | null, IdentityError, never>;
777
- create(input: CreateIdentityInput): Effect.Effect<Profile, IdentityError, never>;
778
- update(input: UpdateIdentityInput): Effect.Effect<Profile, IdentityError, never>;
779
- /** D-ONBOARD (#669): idempotent upsert that marks the identity onboarded. */
780
- completeOnboarding(input: CompleteOnboardingIdentityInput): Effect.Effect<Profile, IdentityError, never>;
781
- }
782
- //#endregion
783
- //#region src/ports/smart-account.d.ts
784
- /** Safe deployment configuration for the Organization setup adapter. */
785
- type SafeDeploymentConfig = {
786
- readonly chainId: ChainId;
787
- readonly rpcUrl: string;
788
- readonly bundlerRpcUrl: string;
789
- readonly receiptTimeoutMs?: DurationMs;
790
- };
791
- /**
792
- * Evidence of a successful Safe deployment.
793
- *
794
- * Every field except `chainId` / `signerAddress` / `safeAddress` is
795
- * optional because the AC8 precheck short-circuit path (Safe already
796
- * on-chain at this address; off-chain receipt evidence unavailable)
797
- * calls the persistence step WITHOUT a `userOpHash`, `txHash`, or
798
- * `blockNumber` — there is no recoverable transaction. Aaron's rule:
799
- * "If there is no TX and it hasn't been deployed then there shouldn't
800
- * be a hash." End-to-end nullable: `v.optional(v.string())` in the
801
- * backend schema.
802
- *
803
- * **`deployedAt` is NOT a field on this type.** The SDK is never the
804
- * oracle for `deployedAt`. The backend (`confirmDeployment` action —
805
- * Convex mutations cannot `fetch`, so the chain re-verification lives
806
- * in an action) derives it from on-chain data — `eth_getUserOperationReceipt`
807
- * for the real-userOp path or `eth_getLogs` for the precheck path —
808
- * then resolves the receipt block's timestamp via `eth_getBlockByNumber`.
809
- * See `packages/sdk/docs/architecture.md` for the deployment trust boundary.
810
- */
811
- type SafeDeploymentEvidence = {
812
- readonly chainId: ChainId;
813
- readonly signerAddress: Address$1;
814
- readonly safeAddress: Address$1;
815
- readonly txHash?: TxHash;
816
- readonly userOpHash?: TxHash;
817
- readonly blockNumber?: BlockNumber;
818
- };
819
- type ProvisionInput = {
820
- readonly authUserId: AuthUserId;
821
- readonly chainId: ChainId;
822
- /** Verified session email. The backend reads the same value from BetterAuth. */
823
- readonly email: Email;
824
- };
825
- /**
826
- * Input to `SmartAccountPort.confirmDeployment` (#161 · γ-B).
827
- *
828
- * The SDK provides evidence pointers; the backend is the oracle for
829
- * `deployedAt`. `evidence.deployedAt` does NOT exist by schema (see
830
- * `SafeDeploymentEvidence`) — the backend derives `deployedAt` from
831
- * the on-chain receipt block via `eth_getBlockByNumber`.
832
- *
833
- * Precheck path: `evidence.userOpHash` omitted; backend scans
834
- * `SafeProxyFactory.ProxyCreation(safeAddress, _)` via `eth_getLogs`.
835
- *
836
- * Real-userOp path: `evidence.userOpHash` populated; backend calls
837
- * `eth_getUserOperationReceipt(userOpHash)` to re-verify and derive.
838
- */
839
- type ConfirmDeploymentInput = {
840
- readonly authUserId: AuthUserId;
841
- readonly chainId: ChainId;
842
- readonly safeAddress: Address$1;
843
- readonly evidence: SafeDeploymentEvidence;
844
- };
845
- /**
846
- * Input to `SmartAccountPort.claim` (PRD #462). The authenticated session
847
- * reports the browser-created signer address; the BACKEND builds and
848
- * bootstrap-signs the claim userOp (deploy + swapOwner) — the consumer signs
849
- * nothing at claim.
850
- */
851
- type ClaimInput = {
852
- readonly authUserId: AuthUserId;
853
- readonly chainId: ChainId;
854
- readonly signerAddress: Address$1;
855
- };
856
- declare const SmartAccountError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
857
- readonly _tag: "SmartAccountError";
858
- } & Readonly<A>;
859
- declare class SmartAccountError extends SmartAccountError_base<{
860
- readonly operation: string;
861
- readonly publicCode: CapxulErrorCode;
862
- readonly publicError: CapxulError;
863
- readonly cause: unknown;
864
- readonly details?: CapxulErrorDetails;
865
- }> {}
866
- interface SmartAccountPort {
867
- loadByAuthUserId(authUserId: AuthUserId): Effect.Effect<SmartAccount | null, SmartAccountError, never>;
868
- loadBySmartAccountAddress(address: Address$1): Effect.Effect<SmartAccount | null, SmartAccountError, never>;
869
- provision(input: ProvisionInput): Effect.Effect<SmartAccount, SmartAccountError, never>;
870
- /**
871
- * Persist on-chain Safe-deployment evidence. The backend re-verifies
872
- * the evidence against chain state and derives `deployedAt` from the
873
- * receipt block's timestamp. Returns the updated `SmartAccount` row.
874
- *
875
- * γ-B trust model: the SDK supplies evidence pointers only. The
876
- * backend is the SOLE oracle for `deployedAt` — see
877
- * `packages/sdk/docs/architecture.md`.
878
- */
879
- confirmDeployment(input: ConfirmDeploymentInput): Effect.Effect<SmartAccount, SmartAccountError, never>;
880
- /**
881
- * Claim the account (PRD #462): the backend builds, bootstrap-signs, and
882
- * submits ONE sponsored userOp — deploy (when undeployed) + swapOwner
883
- * (bootstrap → `signerAddress`). Idempotent; returns the updated row. When
884
- * another claim is in flight the row comes back with `claimedAt: null` —
885
- * callers poll lifecycle until the claim lands.
886
- */
887
- claim(input: ClaimInput): Effect.Effect<SmartAccount, SmartAccountError, never>;
888
- }
889
- //#endregion
890
- //#region src/ports/account-read.d.ts
891
- type ReadAccountBalanceInput = {
892
- readonly chainId: ChainId;
893
- };
894
- type FundFromFaucetInput = {
895
- readonly chainId: ChainId;
896
- readonly amount: Money;
897
- };
898
- type FundFromFaucetResult = {
899
- readonly txHash: string;
900
- };
901
- declare const AccountReadError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
902
- readonly _tag: "AccountReadError";
903
- } & Readonly<A>;
904
- declare class AccountReadError extends AccountReadError_base<{
905
- readonly operation: string;
906
- readonly publicCode: CapxulErrorCode;
907
- readonly publicError: CapxulError;
908
- readonly cause: unknown;
909
- readonly details?: CapxulErrorDetails;
910
- }> {}
911
- /**
912
- * The Account money read joins the `accounts` row with a
913
- * live RPC `balanceOf` pull; the adapter lifts wire integers to `Money`.
914
- */
915
- interface AccountReadPort {
916
- readBalance(input: ReadAccountBalanceInput): Effect.Effect<Account$1, AccountReadError, never>;
917
- fundFromFaucet(input: FundFromFaucetInput): Effect.Effect<FundFromFaucetResult, AccountReadError, never>;
918
- }
919
- //#endregion
920
- //#region src/ports/indexer-read.d.ts
921
- /**
922
- * IndexerReadPort is the SDK's read seam onto the Ponder read model
923
- * (`apps/indexer`). Ponder holds what the chain said; Convex holds what the
924
- * user meant. Nothing here is copied into Convex, nothing waits for a
925
- * finality tag, and no write path may read through this port.
926
- *
927
- * Every read is scoped to one Safe and one page. The indexer accepts only the
928
- * exact compiled statements in `apps/indexer/src/queries.ts`, so the adapter
929
- * that implements this port reproduces those statements byte for byte and the
930
- * service refuses anything else with 403.
931
- */
932
- /** One page of rows for one Safe. `offset` defaults to 0 (the first page). */
933
- interface IndexerReadInput {
934
- /** The Safe the caller owns. The indexer refuses a Safe outside the session claim. */
935
- readonly safe: Address$1;
936
- /** 1 to 1000 inclusive — the indexer's own bound. */
937
- readonly limit: number;
938
- readonly offset?: number;
939
- readonly eventId?: string;
940
- /** Exact Payment lookup for a bounded set of actor-authorized settlement IDs. */
941
- readonly settlements?: readonly string[];
942
- /** Transfer occurrence time in epoch seconds; continuation excludes the last row. */
943
- readonly timeline?: {
944
- readonly from: number;
945
- readonly to: number;
946
- readonly before?: {
947
- readonly timestamp: number;
948
- readonly id: string;
949
- };
950
- };
951
- }
952
- /**
953
- * The chain evidence every indexed row carries. `id` is the logical event id
954
- * `chainId:txHash:transactionLogOrdinal`; it survives a reorg, so it is the
955
- * key a Convex intent row stitches against.
956
- */
957
- interface IndexerEventIdentity {
958
- readonly id: string;
959
- readonly chainId: ChainId;
960
- readonly txHash: TxHash;
961
- readonly transactionLogOrdinal: number;
962
- /**
963
- * The block-global log index of the same log, as the transaction receipt
964
- * reports it. The ordinal above is the identity; this is the key Convex
965
- * settles a Payment on (P12).
966
- */
967
- readonly logIndex: number;
968
- readonly blockNumber: bigint;
969
- readonly blockHash: string;
970
- /** Block timestamp in epoch seconds. */
971
- readonly timestamp: bigint;
972
- }
973
- interface IndexerTransferRow extends IndexerEventIdentity {
974
- /** Timeline projection only. Null means no protocol event owns this Transfer. */
975
- readonly paymentSettlementId?: string | null;
976
- readonly assetId: AssetId;
977
- readonly token: Address$1;
978
- readonly from: Address$1;
979
- readonly to: Address$1;
980
- /**
981
- * Raw token units, exact. This is an evidence boundary, so the row never
982
- * carries Money or AssetAmount: the reader owns the asset's decimals.
983
- */
984
- readonly amount: bigint;
985
- }
986
- interface IndexerPaymentRow extends IndexerEventIdentity {
987
- readonly contract: Address$1;
988
- /** The protocol settlement id a Convex Payment command stitches against. */
989
- readonly settlementId: string;
990
- readonly sender: Address$1;
991
- readonly recipient: Address$1;
992
- readonly assetId: AssetId;
993
- readonly token: Address$1;
994
- /** Raw token units, exact. */
995
- readonly amount: bigint;
996
- readonly kind: number;
997
- readonly documentHash: string;
998
- }
999
- /** A row of the indexer's signed-transfer `balance` view. */
1000
- interface IndexerBalanceRow {
1001
- readonly chainId: ChainId;
1002
- readonly assetId: AssetId;
1003
- readonly address: Address$1;
1004
- /** Raw token units, exact. */
1005
- readonly amount: bigint;
1006
- }
1007
- /** One chain's sync position, from the indexer's native `/status` route. */
1008
- interface IndexerChainStatus {
1009
- readonly chain: string;
1010
- readonly chainId: ChainId;
1011
- readonly blockNumber: bigint;
1012
- /** Block timestamp in epoch seconds. Its age is the freshness label. */
1013
- readonly blockTimestamp: bigint;
1014
- }
1015
- /**
1016
- * The tables this seam reads today. P04 adds the authority rows (`safe`,
1017
- * `safe_event`, `roles_module`) and P05 adds `commitment`: each is one more
1018
- * entry here plus its statement and decoder.
1019
- */
1020
- interface IndexerRowsByTable {
1021
- readonly transfer: readonly IndexerTransferRow[];
1022
- readonly payment: readonly IndexerPaymentRow[];
1023
- readonly balance: readonly IndexerBalanceRow[];
1024
- }
1025
- type IndexerTable = keyof IndexerRowsByTable;
1026
- declare const IndexerReadError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
1027
- readonly _tag: "IndexerReadError";
1028
- } & Readonly<A>;
1029
- declare class IndexerReadError extends IndexerReadError_base<{
1030
- readonly operation: string;
1031
- readonly publicCode: CapxulErrorCode;
1032
- readonly publicError: CapxulError;
1033
- readonly cause: unknown;
1034
- readonly details?: CapxulErrorDetails;
1035
- }> {}
1036
- interface IndexerReadPort {
1037
- /** One page of rows, newest block first. An empty page is a value, not an error. */
1038
- read<T extends IndexerTable>(table: T, input: IndexerReadInput): Effect.Effect<IndexerRowsByTable[T], IndexerReadError>;
1039
- /**
1040
- * The same page over the indexer's live stream. The first snapshot is
1041
- * `loading`; each later snapshot carries the whole page again. The indexer
1042
- * closes the stream on token expiry or revoked authority, which arrives as
1043
- * one `error` snapshot — the caller re-reads with a refreshed token.
1044
- *
1045
- * @internal-use — substrate reactive transport, like `ConvexCallPort.subscribe`.
1046
- */
1047
- subscribe<T extends IndexerTable>(table: T, input: IndexerReadInput, callback: (snapshot: Snapshot<IndexerRowsByTable[T]>) => void): Effect.Effect<Unsubscribe, IndexerReadError>;
1048
- /** Sync position per chain. Unauthenticated: a stale index is not a refusal. */
1049
- readonly status: Effect.Effect<readonly IndexerChainStatus[], IndexerReadError>;
1050
- }
1051
- //#endregion
1052
- //#region src/flows/types.d.ts
1053
- /** The runtime port bundle that `assembleCapxulClient` uses. */
1054
- interface FlowPorts {
1055
- readonly authClient: AuthClientPort;
1056
- readonly authCache: AuthCachePort;
1057
- readonly identity: IdentityPort;
1058
- readonly smartAccount: SmartAccountPort;
1059
- readonly accountRead: AccountReadPort;
1060
- readonly bootstrap: BootstrapPort;
1061
- readonly clock: ClockPort;
1062
- readonly telemetry: TelemetryPort;
1063
- readonly convexCall: ConvexCallPort;
1064
- /**
1065
- * The Ponder read seam (P02). Optional: it is present only when the client
1066
- * was given an indexer origin, and every existing flow works without it.
1067
- */
1068
- readonly indexerRead?: IndexerReadPort;
1069
- }
1070
- /** Legacy method input retained by the imperative auth surface. */
1071
- interface ExternalSigner {
1072
- readonly address: Address$1;
1073
- readonly signedProof: string;
1074
- }
1075
- //#endregion
1076
- //#region src/surface/org-lifecycle.d.ts
1077
- type OrgSetupStep = "preparingFounderAccount" | "awaitingFounderAuthorization" | "submittingBootstrap" | "confirmingBootstrap";
1078
- /** Leak-safe readiness for exactly one Organization. */
1079
- type OrgLifecycle = {
1080
- readonly status: "loading";
1081
- readonly orgId: OrgId;
1082
- } | {
1083
- readonly status: "settingUp";
1084
- readonly orgId: OrgId;
1085
- readonly step: OrgSetupStep;
1086
- } | {
1087
- readonly status: "ready";
1088
- readonly orgId: OrgId;
1089
- readonly canTransact: true;
1090
- } | {
1091
- readonly status: "failed";
1092
- readonly orgId: OrgId;
1093
- readonly at: OrgSetupStep;
1094
- readonly error: CapxulError;
1095
- readonly retryable: boolean;
1096
- };
1097
- type StartOrResumeOrganizationInput = {
1098
- readonly name: string;
1099
- readonly handle: string;
1100
- readonly country: string;
1101
- /** #1064: optional onboarding-collected description + size bucket. */
1102
- readonly bio?: string;
1103
- readonly size?: string;
1104
- /** #1955: storage id from `media.uploadImage`, recorded on the org insert. */
1105
- readonly logoStorageId?: string;
1106
- /** @internal Safe trace/correlation carriage owned by the identity flow. */
1107
- readonly observationContext?: WireObservationContext;
1108
- };
1109
- type OrganizationSetupStepInput = {
1110
- readonly orgId: OrgId;
1111
- readonly signal?: AbortSignal;
1112
- /** @internal Safe trace/correlation carriage owned by the identity flow. */
1113
- readonly observationContext?: WireObservationContext;
1114
- /**
1115
- * @internal #1655: milliseconds the identity flow waited before this
1116
- * confirmation attempt. Absent on the first attempt. The backend copies it
1117
- * onto `organization_creation_failed` as `backoff_ms`.
1118
- */
1119
- readonly retryDelayMs?: number;
1120
- };
1121
- type RecordOrganizationSetupFailureInput = {
1122
- readonly orgId: OrgId;
1123
- readonly error: CapxulError;
1124
- readonly retryable: boolean;
1125
- /** @internal Safe trace/correlation carriage owned by the identity flow. */
1126
- readonly observationContext?: WireObservationContext;
1127
- };
1128
- /**
1129
- * Internal capability set used by the Core SDK's deep Organization boundary.
1130
- * Consumers never coordinate these steps directly. Production composition
1131
- * supplies them; hermetic contract tests provide a stateful implementation.
1132
- */
1133
- interface OrganizationSetupOps {
1134
- startOrResume(input: StartOrResumeOrganizationInput): Promise<CapxulResult<{
1135
- readonly orgId: OrgId;
1136
- readonly lifecycle: OrgLifecycle;
1137
- }>>;
1138
- /** Completes and verifies the founder Account ownership handoff. */
1139
- prepareFounderAccount(input: OrganizationSetupStepInput): Promise<CapxulResult<OrgLifecycle>>;
1140
- /** Obtains configured signer authorization and submits the bootstrap once. */
1141
- authorizeAndSubmitBootstrap(input: OrganizationSetupStepInput): Promise<CapxulResult<OrgLifecycle>>;
1142
- /** Resumes a recorded provider-known submission without invoking the signer. */
1143
- resumeSubmittedBootstrap(input: OrganizationSetupStepInput): Promise<CapxulResult<OrgLifecycle>>;
1144
- /** Confirms a previously recorded submission without requesting authorization again. */
1145
- confirmSubmittedBootstrap(input: OrganizationSetupStepInput): Promise<CapxulResult<OrgLifecycle>>;
1146
- recordFailure(input: RecordOrganizationSetupFailureInput): Promise<CapxulResult<OrgLifecycle>>;
1147
- loadLifecycle(input: {
1148
- readonly orgId: OrgId;
1149
- readonly observationContext?: WireObservationContext;
1150
- }): Promise<CapxulResult<OrgLifecycle>>;
1151
- /** Resets durable failure state only; the Core SDK resumes the correct step. */
1152
- retry(input: OrganizationSetupStepInput): Promise<CapxulResult<OrgLifecycle>>;
1153
- }
1154
- //#endregion
1155
- //#region src/flows/identity.d.ts
1156
- interface IdentityActor extends Actor<IdentityState, IdentityEvent, RefusalReason> {
1157
- /** Full provider session retained beside the deliberately minimal model session. */
1158
- readonly authSession: () => AuthSession | null;
1159
- /** Trust a cache-resumed provider session before a later ReadSession verifies it. */
1160
- readonly restoreAuthSession: (session: AuthSession, controls?: InvocationControls) => Effect.Effect<IdentityState, ActorFailure<RefusalReason | CapxulErrorCode>>;
1161
- }
1162
- //#endregion
1163
- //#region src/surface/auth.d.ts
1164
- type AuthMethodOptions = InvocationControls;
1165
- type SignInOptions = AuthMethodOptions;
1166
- interface AuthMethods {
1167
- canSendOtp(input: {
1168
- readonly email: string;
1169
- }, options?: AuthMethodOptions): Promise<CapxulResult<CanSendOtpStatus>>;
1170
- signIn(input: {
1171
- readonly email: string;
1172
- }, options?: SignInOptions): Promise<CapxulResult<{
1173
- readonly sessionId: string;
1174
- readonly expiresAt: number;
1175
- }>>;
1176
- verifyOtp(input: {
1177
- readonly email: string;
1178
- readonly code: string;
1179
- readonly signer?: ExternalSigner;
1180
- }, options?: AuthMethodOptions): Promise<CapxulResult<Session$1>>;
1181
- signOut(options?: AuthMethodOptions): Promise<CapxulResult<void>>;
1182
- getSession(options?: AuthMethodOptions): Promise<CapxulResult<Session$1 | null>>;
1183
- }
1184
- //#endregion
1185
- //#region src/surface/smart-account.d.ts
1186
- interface SmartAccountMethods {
1187
- loadCurrent(options?: {
1188
- readonly signal?: AbortSignal;
1189
- }): Promise<CapxulResult<SmartAccount$1 | null>>;
1190
- provision(input?: {
1191
- readonly externalSigner?: ExternalSigner;
1192
- }): Promise<CapxulResult<SmartAccount$1>>;
1193
- }
1194
- //#endregion
1195
- //#region src/surface/identity.d.ts
1196
- /**
1197
- * #1955: what a create call may carry besides the three required fields — the
1198
- * photo already uploaded and the payout addresses the form collected.
1199
- */
1200
- interface ProfileCarriage {
1201
- /** Storage id from `media.uploadImage`. */
1202
- readonly imageStorageId?: string;
1203
- readonly payoutAddresses?: readonly PayoutAddress[];
1204
- }
1205
- interface CompleteProfileInput extends ProfileCarriage {
1206
- readonly displayName: string;
1207
- readonly country: string;
1208
- readonly handle: string;
1209
- }
1210
- interface IdentityMethods {
1211
- loadCurrent(options?: {
1212
- readonly signal?: AbortSignal;
1213
- }): Promise<CapxulResult<Profile$1 | null>>;
1214
- /** Complete the Person profile. A normalized, globally unique handle is required. */
1215
- completeProfile(profile: CompleteProfileInput, options?: {
1216
- readonly signal?: AbortSignal;
1217
- }): Promise<CapxulResult<Profile$1>>;
1218
- /**
1219
- * #1062: availability probe for the handle the user is typing. Returns the
1220
- * canonical stored form so the UI can echo it.
1221
- */
1222
- handleAvailable(handle: string, options?: {
1223
- readonly signal?: AbortSignal;
1224
- }): Promise<CapxulResult<{
1225
- readonly available: boolean;
1226
- readonly normalized: string;
1227
- }>>;
1228
- }
1229
- //#endregion
1230
- //#region src/surface/account-lifecycle.d.ts
1231
- type ProvisioningFailureStep = "wallet" | "identity" | "provision" | "deploy";
1232
- type ProvisioningPhase = {
1233
- readonly status: "idle";
1234
- } | {
1235
- readonly status: "wallet";
1236
- } | {
1237
- readonly status: "identity";
1238
- } | {
1239
- readonly status: "provision";
1240
- } | {
1241
- readonly status: "deploy";
1242
- } | {
1243
- readonly status: "ready";
1244
- } | {
1245
- readonly status: "failed";
1246
- readonly at: ProvisioningFailureStep;
1247
- readonly error: CapxulError;
1248
- };
1249
- type AccountSetupStep = "connecting" | "confirmingIdentity" | "registering" | "activating";
1250
- type AccountLifecycle = {
1251
- readonly status: "loading";
1252
- } | {
1253
- readonly status: "settingUp";
1254
- readonly step: AccountSetupStep;
1255
- } | {
1256
- readonly status: "ready";
1257
- readonly accountId: string;
1258
- readonly canTransact: boolean;
1259
- } | {
1260
- readonly status: "failed";
1261
- readonly at: AccountSetupStep;
1262
- readonly error: CapxulError;
1263
- };
1264
- declare function isSettingUpLifecycle(lifecycle: AccountLifecycle): boolean;
1265
- //#endregion
1266
- //#region src/surface/payment-command-execution.d.ts
1267
- /** Return one stable fingerprint for one JSON payment intent. */
1268
- declare function fingerprintPaymentIntent(intent: unknown): Promise<string>;
1269
- //#endregion
1270
- //#region src/surface/money.d.ts
1271
- type ActorReference = {
1272
- readonly kind: "personal";
1273
- } | {
1274
- readonly kind: "organization";
1275
- readonly organizationId: string;
1276
- };
1277
- type TargetReference = {
1278
- readonly kind: "handle";
1279
- readonly handle: string;
1280
- } | {
1281
- readonly kind: "email";
1282
- readonly email: string;
1283
- } | {
1284
- readonly kind: "address";
1285
- readonly address: Address$1;
1286
- } | {
1287
- readonly kind: "party";
1288
- readonly partyId: PartyId;
1289
- };
1290
- interface ResolvedTarget {
1291
- readonly reference: TargetReference;
1292
- readonly label: string;
1293
- readonly status: RecipientResolution["status"];
1294
- readonly kind: "person" | "organization" | "external_address" | "unresolved";
1295
- readonly safeAddress: Address$1;
1296
- readonly isCapxulAccount: boolean;
1297
- readonly partyId?: PartyId;
1298
- readonly handle?: string;
1299
- readonly requiresAcknowledgement?: true;
1300
- readonly capabilities: {
1301
- readonly canPay: boolean;
1302
- readonly canRequest: boolean;
1303
- readonly canPayout: boolean;
1304
- };
1305
- }
1306
- /**
1307
- * R09 (#1967): the declared option type is the `InvocationControls` the money
1308
- * surface already forwards to `deps.invocationControls`, named here exactly as
1309
- * R02 named it on the address book and R13 on payroll. A caller that captured
1310
- * one user attempt can hand the same `correlation_id`/`journey_id` to the read
1311
- * it starts, so the read joins that attempt instead of standing alone.
1312
- * `{ signal }` callers are unaffected.
1313
- */
1314
- type PaymentReadOptions = InvocationControls;
1315
- interface TargetsMethods {
1316
- resolve(reference: TargetReference, options?: PaymentReadOptions): Promise<CapxulResult<ResolvedTarget>>;
1317
- }
1318
- type Ref$1 = {
1319
- readonly kind: "handle";
1320
- readonly handle: string;
1321
- } | {
1322
- readonly kind: "email";
1323
- readonly email: string;
1324
- } | {
1325
- readonly kind: "address";
1326
- readonly address: Address$1;
1327
- } | {
1328
- readonly kind: "party";
1329
- readonly partyId: PartyId;
1330
- };
1331
- interface MeProfile {
1332
- readonly authUserId: string;
1333
- readonly email: string;
1334
- readonly displayName: string | null;
1335
- }
1336
- interface DepositInstructions {
1337
- readonly accountKind: "personalSafe" | "orgTreasury";
1338
- readonly chainId: number;
1339
- readonly network: "base-sepolia";
1340
- readonly currency: "USD";
1341
- readonly address: string;
1342
- readonly label: string;
1343
- }
1344
- interface RecipientResolution {
1345
- readonly status: "known_party" | "new_email" | "external_address";
1346
- readonly kind: "party" | "email" | "external_address";
1347
- readonly locatorKind: Ref$1["kind"];
1348
- readonly recipient: Ref$1;
1349
- readonly label: string;
1350
- readonly safeAddress: string;
1351
- readonly isCapxulAccount: boolean;
1352
- readonly partyId?: string;
1353
- readonly partyKind?: "person" | "org";
1354
- readonly handle?: string;
1355
- readonly email?: string;
1356
- readonly address?: string;
1357
- readonly requiresAcknowledgement?: true;
1358
- }
1359
- interface MeMethods {
1360
- get(options?: {
1361
- readonly signal?: AbortSignal;
1362
- }): Promise<CapxulResult<MeProfile>>;
1363
- /** R08 (#1966): accepts a captured attempt, exactly as the treasury read does. */
1364
- depositInstructions(options?: InvocationControls): Promise<CapxulResult<DepositInstructions>>;
1365
- }
1366
- interface PaymentMoney {
1367
- readonly currency: string;
1368
- readonly value: string;
1369
- readonly decimals: number;
1370
- }
1371
- type PaymentStatus = PaymentStatus$1;
1372
- type PaymentDirection = PaymentDirection$1;
1373
- type PaymentType = PaymentType$1;
1374
- type PaymentDocumentKind = PaymentDocumentKind$1;
1375
- interface PaymentDocumentRef {
1376
- readonly documentHash: string;
1377
- readonly kind: PaymentDocumentKind;
1378
- readonly title?: string;
1379
- readonly uri?: string;
1380
- readonly issuedAt?: number;
1381
- }
1382
- type PaymentTiming = {
1383
- readonly kind: "instant";
1384
- } | {
1385
- readonly kind: "scheduled";
1386
- readonly at: number;
1387
- } | {
1388
- readonly kind: "stream";
1389
- readonly startsAt: number;
1390
- readonly endsAt: number;
1391
- readonly cliffAt?: number;
1392
- };
1393
- interface Payment {
1394
- readonly id: string;
1395
- readonly status: PaymentStatus;
1396
- readonly amount: PaymentMoney;
1397
- readonly paymentType: PaymentType;
1398
- readonly direction: PaymentDirection;
1399
- readonly counterpartyLabel: string;
1400
- readonly receipt: {
1401
- readonly chainId: number;
1402
- readonly transactionHash: string;
1403
- } | null;
1404
- readonly recipient: {
1405
- readonly kind: "party";
1406
- readonly partyId: string;
1407
- readonly label: string;
1408
- } | {
1409
- readonly kind: "external_address";
1410
- readonly label: string;
1411
- };
1412
- readonly documents: readonly PaymentDocumentRef[];
1413
- readonly timing: PaymentTiming;
1414
- readonly released: PaymentMoney;
1415
- readonly availableToClaim: PaymentMoney;
1416
- readonly execution?: PaymentExecutionView;
1417
- readonly createdAt: number;
1418
- readonly updatedAt: number;
1419
- }
1420
- interface PaymentsPayInput {
1421
- readonly actor?: ActorReference;
1422
- readonly to: TargetReference;
1423
- readonly amount: PaymentMoney;
1424
- readonly externalAddressAcknowledged?: true;
1425
- /**
1426
- * How the payment is classified on the ledger. When a `document` is
1427
- * attached, the type derived from the document kind is AUTHORITATIVE
1428
- * (memo → unspecified, invoice → invoice, payslip → payroll, receipt →
1429
- * reimbursement) — an explicit conflicting value is rejected with
1430
- * INVALID_INPUT ("must match the attached document kind"). With no
1431
- * document the explicit value is honored, defaulting to "unspecified".
1432
- */
1433
- readonly paymentType?: PaymentType;
1434
- /** Full EIP-712 document envelope; hashed + stored, committed on-chain. */
1435
- readonly document?: AttachablePaymentDocumentEnvelopeV1;
1436
- /**
1437
- * Payment timing. Omitted means `instant`.
1438
- * A `scheduled`/`stream` clause turns the payment into a Commitment
1439
- * (escrow-vest-claim) backed by `CapxulPayments.createCommitment`.
1440
- */
1441
- readonly timing?: PaymentTiming;
1442
- /**
1443
- * #592: itemized line items backing an Invoice `document`. The backend asserts
1444
- * `hashLineItems(lineItems) === document.lineItemsHash` AND `Σ(quantity ×
1445
- * unitMinor) === document.amount`, then persists the list for itemized render.
1446
- */
1447
- readonly lineItems?: readonly LineItemV1[];
1448
- }
1449
- type DestinationKind = "bank_account" | "mobile_money" | "external_account";
1450
- type DestinationRail = {
1451
- readonly kind: "bank";
1452
- readonly country: string;
1453
- readonly currency: string;
1454
- } | {
1455
- readonly kind: "mobile_money";
1456
- readonly country: string;
1457
- readonly currency: string;
1458
- readonly provider: string;
1459
- } | {
1460
- readonly kind: "chain";
1461
- readonly network: string;
1462
- readonly asset?: string;
1463
- };
1464
- type DestinationPayload = {
1465
- readonly accountHolderName: string;
1466
- readonly bankName: string;
1467
- readonly country: string;
1468
- readonly currency: string;
1469
- readonly accountNumberLast4: string;
1470
- } | {
1471
- readonly provider: string;
1472
- readonly country: string;
1473
- readonly currency: string;
1474
- readonly phoneNumberLast4: string;
1475
- } | {
1476
- readonly network: "base-sepolia" | "solana-devnet" | "starknet-sepolia";
1477
- readonly address: string;
1478
- };
1479
- interface Destination {
1480
- readonly id: string;
1481
- readonly counterpartyId: string;
1482
- /** #1063: null exactly when `ownerScope === "self"`. */
1483
- readonly ref: Ref$1 | null;
1484
- /** Derived from `ref`; null for self-owned rows. */
1485
- readonly target: TargetReference | null;
1486
- readonly kind: DestinationKind;
1487
- readonly rail: DestinationRail;
1488
- /**
1489
- * #1063: "self" = the actor's own payout destination; "counterparty" = the
1490
- * address-book shape. The mapping always sets it (wire absence ⇒ "counterparty").
1491
- */
1492
- readonly ownerScope: "self" | "counterparty";
1493
- readonly label: string | null;
1494
- readonly payload: DestinationPayload;
1495
- readonly createdAt: number;
1496
- readonly updatedAt: number;
1497
- }
1498
- /** #1063 ratified shape: your own payout destination is `target: { self: true }`. */
1499
- type SelfTarget = {
1500
- readonly self: true;
1501
- };
1502
- /** #1063: exactly one of `target` (counterparty or `{ self: true }`) or `ref`. */
1503
- interface DestinationAddInput {
1504
- readonly actor?: ActorReference;
1505
- readonly target?: TargetReference | SelfTarget;
1506
- readonly ref?: Ref$1;
1507
- readonly kind: DestinationKind;
1508
- readonly label?: string;
1509
- readonly payload: DestinationPayload;
1510
- }
1511
- interface DestinationListInput {
1512
- readonly actor?: ActorReference;
1513
- /** #1063: `{ self: true }` narrows to the actor's own payout destinations. */
1514
- readonly target?: TargetReference | SelfTarget;
1515
- readonly ref?: Ref$1;
1516
- readonly kind?: DestinationKind;
1517
- }
1518
- interface DestinationRemoveInput {
1519
- readonly actor?: ActorReference;
1520
- readonly destinationId: string;
1521
- }
1522
- interface DestinationsMethods {
1523
- add(input: DestinationAddInput, options?: {
1524
- readonly signal?: AbortSignal;
1525
- }): Promise<CapxulResult<Destination>>;
1526
- list(input: DestinationListInput, options?: {
1527
- readonly signal?: AbortSignal;
1528
- }): Promise<CapxulResult<readonly Destination[]>>;
1529
- remove(input: DestinationRemoveInput, options?: {
1530
- readonly signal?: AbortSignal;
1531
- }): Promise<CapxulResult<{
1532
- readonly id: string;
1533
- }>>;
1534
- }
1535
- /** The one name for what an activity row IS. */
1536
- type ActivityKind = "payment" | "movement";
1537
- /** `createdAt` bounds in epoch milliseconds. Both ends are inclusive. */
1538
- interface ActivityRange {
1539
- readonly from?: number;
1540
- readonly to?: number;
1541
- }
1542
- interface ActivityFilter {
1543
- readonly kind?: ActivityKind;
1544
- readonly direction?: PaymentDirection;
1545
- /** Payment rows only. A status filter therefore excludes Movements, which have none. */
1546
- readonly status?: readonly PaymentStatus[];
1547
- }
1548
- interface ActivityListParams {
1549
- readonly actor?: ActorReference;
1550
- readonly cursor?: string;
1551
- /** 1..100, default 25. The backend rejects anything outside that band. */
1552
- readonly limit?: number;
1553
- readonly range?: ActivityRange;
1554
- readonly filter?: ActivityFilter;
1555
- }
1556
- type ActivityReference = {
1557
- readonly kind: "payment";
1558
- readonly id: string;
1559
- readonly actor?: ActorReference;
1560
- } | {
1561
- readonly kind: "movement";
1562
- readonly id: string;
1563
- };
1564
- type ActivityItem = {
1565
- readonly kind: "payment";
1566
- readonly execution?: PaymentExecutionView;
1567
- readonly id: string;
1568
- readonly ledgerKind: "Payment" | "Payout" | "Deposit";
1569
- readonly status: PaymentStatus;
1570
- /** What the payment is FOR. On the list row so a title needs no second read. */
1571
- readonly paymentType: PaymentType;
1572
- readonly amount: PaymentMoney;
1573
- readonly direction: PaymentDirection;
1574
- readonly counterpartyLabel: string;
1575
- readonly receipt: {
1576
- readonly chainId: number;
1577
- readonly transactionHash: string;
1578
- } | null;
1579
- readonly createdAt: number;
1580
- readonly updatedAt: number;
1581
- } | {
1582
- readonly kind: "movement";
1583
- readonly id: string;
1584
- readonly classification: "movement_only_outflow";
1585
- readonly amount: PaymentMoney;
1586
- readonly direction: PaymentDirection;
1587
- /** Short-form counterparty address today. */
1588
- readonly counterpartyLabel: string;
1589
- readonly receipt: {
1590
- readonly chainId: number;
1591
- readonly transactionHash: string;
1592
- };
1593
- readonly createdAt: number;
1594
- readonly updatedAt: number;
1595
- };
1596
- interface ActivityPage {
1597
- /** Usable fallback data omits indexed movements; never present it as complete. */
1598
- readonly readWarning?: "indexer-unavailable";
1599
- readonly items: readonly ActivityItem[];
1600
- readonly cursor: string | null;
1601
- readonly checkpoint: number;
1602
- /** Server read time, so a consumer can say which of two reads is older. */
1603
- readonly observedAt: number;
1604
- }
1605
- interface ActivitySummaryParams {
1606
- readonly actor?: ActorReference;
1607
- readonly window?: ActivityRange;
1608
- }
1609
- interface ActivitySummaryTotal {
1610
- readonly currency: string;
1611
- readonly decimals: number;
1612
- /** Integer raw-unit strings. `net` is `in - out` and may be negative. */
1613
- readonly in: string;
1614
- readonly out: string;
1615
- readonly net: string;
1616
- /** The `in` share that is not yet terminal. */
1617
- readonly pendingIn: string;
1618
- }
1619
- interface ActivitySummary {
1620
- readonly readWarning?: ActivityPage["readWarning"];
1621
- readonly window: {
1622
- readonly from: number | null;
1623
- readonly to: number | null;
1624
- };
1625
- /** One bucket per currency, and EMPTY when the window holds no activity. */
1626
- readonly totals: readonly ActivitySummaryTotal[];
1627
- /**
1628
- * Every activity row in the window, whatever its direction or status. It
1629
- * therefore counts rows that move no money into the totals — a payment the
1630
- * actor sent to itself, and a cancelled one.
1631
- */
1632
- readonly count: number;
1633
- readonly observedAt: number;
1634
- }
1635
- interface PaymentActivityEvidence {
1636
- readonly chainId: 84532;
1637
- readonly contractAddress: string;
1638
- readonly tokenAddress: string;
1639
- readonly transactionHash: string;
1640
- readonly blockNumber: number;
1641
- readonly blockHash: string;
1642
- readonly inclusion: "included";
1643
- readonly verification: "verified";
1644
- /** @deprecated Use `inclusion` and `verification`. */
1645
- readonly finality: "finalized";
1646
- readonly paymentEventLogIndex: number | null;
1647
- readonly transferLogIndex: number;
1648
- readonly settlementId: string | null;
1649
- readonly source: string;
1650
- readonly destination: string;
1651
- readonly rawAmount: string;
1652
- readonly link: {
1653
- readonly paymentId: string;
1654
- readonly movementId: string | null;
1655
- readonly transactionHash: string;
1656
- };
1657
- }
1658
- interface MovementActivityEvidence {
1659
- readonly chainId: number;
1660
- readonly contractAddress: string;
1661
- readonly tokenAddress: string;
1662
- readonly transactionHash: string;
1663
- readonly blockNumber: number;
1664
- readonly blockHash: string;
1665
- readonly inclusion: "included";
1666
- readonly verification: "verified";
1667
- /** @deprecated Use `inclusion` and `verification`. */
1668
- readonly canonicalState: "finalized";
1669
- readonly transferLogIndex: number;
1670
- readonly source: string;
1671
- readonly destination: string;
1672
- readonly rawAmount: string;
1673
- readonly link: {
1674
- readonly movementId: string;
1675
- readonly depositPaymentId: string | null;
1676
- };
1677
- }
1678
- /**
1679
- * The overlay one actor keeps over one activity row. `actor` and `lastEditor`
1680
- * are the backend's own `ActorRef`, the same shape `MovementAnnotation` carried
1681
- * before the overlay generalized past Movements.
1682
- */
1683
- interface ActivityAnnotation {
1684
- readonly reference: ActivityReference;
1685
- readonly actor: ActorRef;
1686
- readonly counterpartyLabel?: string;
1687
- readonly accountingCategory?: string;
1688
- readonly memo?: string;
1689
- readonly lastEditor: ActorRef;
1690
- readonly updatedAt: number;
1691
- }
1692
- type ActivityDetail = {
1693
- readonly kind: "payment";
1694
- readonly payment: Payment;
1695
- readonly annotation: ActivityAnnotation | null;
1696
- readonly evidence: PaymentActivityEvidence | null;
1697
- } | {
1698
- readonly kind: "movement";
1699
- readonly movementId: string;
1700
- readonly annotation: ActivityAnnotation | null;
1701
- readonly evidence: MovementActivityEvidence;
1702
- };
1703
- interface ActivityAnnotationInput {
1704
- readonly actor?: ActorReference;
1705
- /** Any activity row, not only a Movement. */
1706
- readonly reference: ActivityReference;
1707
- readonly counterpartyLabel?: string;
1708
- readonly accountingCategory?: string;
1709
- readonly memo?: string;
1710
- }
1711
- /**
1712
- * #1960 R02: the declared option type is the `InvocationControls` these methods
1713
- * have always forwarded to `deps.invocationControls`, so an Activity action can
1714
- * carry the correlation its UI observation already used. `{ signal }` callers
1715
- * are unaffected.
1716
- */
1717
- interface ActivityMethods {
1718
- /**
1719
- * Tell the caller when the indexed page for this actor's Safe changed, over
1720
- * the indexer's one live connection. The callback carries no rows: it is the
1721
- * signal to re-read `list` or `summary`. Without an indexer this resolves a
1722
- * no-op teardown, so a caller needs no branch.
1723
- *
1724
- * @internal-use — substrate reactive transport, like `ConvexCallPort.subscribe`.
1725
- */
1726
- subscribe(onChange: () => void, params?: {
1727
- readonly actor?: ActorReference;
1728
- }, options?: InvocationControls): Promise<CapxulResult<() => void>>;
1729
- list(params?: ActivityListParams, options?: InvocationControls): Promise<CapxulResult<ActivityPage>>;
1730
- summary(params?: ActivitySummaryParams, options?: InvocationControls): Promise<CapxulResult<ActivitySummary>>;
1731
- get(reference: ActivityReference, options?: InvocationControls & {
1732
- readonly actor?: ActorReference;
1733
- }): Promise<CapxulResult<ActivityDetail | null>>;
1734
- annotate(input: ActivityAnnotationInput, options?: InvocationControls): Promise<CapxulResult<ActivityAnnotation>>;
1735
- }
1736
- interface OfframpQuoteInput {
1737
- readonly actor?: ActorReference;
1738
- readonly destinationId: string;
1739
- readonly amount: PaymentMoney;
1740
- }
1741
- interface OfframpQuote {
1742
- readonly id: string;
1743
- readonly input: OfframpQuoteInput;
1744
- readonly expiresAt: number;
1745
- readonly receivedAmount: PaymentMoney;
1746
- readonly fee: PaymentMoney;
1747
- }
1748
- interface OfframpStatus {
1749
- readonly id: string;
1750
- readonly status: "pending" | "processing" | "completed" | "failed" | "cancelled";
1751
- readonly paymentId: string | null;
1752
- readonly destinationId: string;
1753
- readonly updatedAt: number;
1754
- }
1755
- interface OfframpMethods {
1756
- quote(input: OfframpQuoteInput, options?: {
1757
- readonly signal?: AbortSignal;
1758
- }): Promise<CapxulResult<OfframpQuote>>;
1759
- status(offrampId: string, options?: {
1760
- readonly signal?: AbortSignal;
1761
- }): Promise<CapxulResult<OfframpStatus>>;
1762
- }
1763
- interface PaymentDocumentVerification {
1764
- readonly documentHash: string;
1765
- readonly ok: boolean;
1766
- readonly derivedHash: string;
1767
- readonly kind: PaymentDocumentKind;
1768
- }
1769
- /**
1770
- * #577 render-on-demand result. `html` is self-contained user-visible document
1771
- * HTML (stylesheet + rendered document). The MCP `paymentDocuments.render` tool
1772
- * exposes only `{documentHash, kind, ok}` to the model and returns `html` in an
1773
- * audience:["user"] content block (#506 redaction matrix).
1774
- */
1775
- interface PaymentDocumentRender {
1776
- readonly documentHash: string;
1777
- readonly ok: boolean;
1778
- readonly kind: PaymentDocumentKind;
1779
- readonly html: string;
1780
- }
1781
- /**
1782
- * The public Payments surface uses product-level methods. A settled receipt can
1783
- * include `chainId` and `transactionHash`. Internal custody fields stay private.
1784
- */
1785
- interface PaymentsMethods {
1786
- pay(input: PaymentsPayInput, options?: {
1787
- readonly signal?: AbortSignal;
1788
- }): Promise<CapxulResult<Payment>>;
1789
- retry(paymentId: string, options?: {
1790
- readonly signal?: AbortSignal;
1791
- }): Promise<CapxulResult<readonly Payment[]>>;
1792
- createCommitment(input: PaymentsPayInput & {
1793
- readonly timing: Exclude<PaymentTiming, {
1794
- readonly kind: "instant";
1795
- }>;
1796
- }, options?: {
1797
- readonly signal?: AbortSignal;
1798
- }): Promise<CapxulResult<Payment>>;
1799
- claim(paymentId: string, options?: {
1800
- readonly signal?: AbortSignal;
1801
- }): Promise<CapxulResult<Payment>>;
1802
- list(options?: PaymentReadOptions): Promise<CapxulResult<readonly Payment[]>>;
1803
- get(paymentId: string, options?: PaymentReadOptions): Promise<CapxulResult<Payment | null>>;
1804
- cancel(paymentId: string, options?: {
1805
- readonly signal?: AbortSignal;
1806
- }): Promise<CapxulResult<Payment>>;
1807
- redirect(input: {
1808
- readonly paymentId: string;
1809
- readonly to: TargetReference;
1810
- }, options?: {
1811
- readonly signal?: AbortSignal;
1812
- }): Promise<CapxulResult<Payment>>;
1813
- }
1814
- interface PaymentDocumentsMethods {
1815
- verify(documentHash: string, options?: {
1816
- readonly signal?: AbortSignal;
1817
- }): Promise<CapxulResult<PaymentDocumentVerification>>;
1818
- /**
1819
- * #577: render-on-demand. Loads the owner's stored document by `documentHash`,
1820
- * re-verifies its EIP-712 hash, and renders it to self-contained HTML using the
1821
- * verified stored line items. Returns `{documentHash, kind, ok, html}`.
1822
- */
1823
- render(documentHash: string, options?: {
1824
- readonly signal?: AbortSignal;
1825
- }): Promise<CapxulResult<PaymentDocumentRender>>;
1826
- }
1827
- interface FinancialOpsMethods {
1828
- readonly me: MeMethods;
1829
- readonly targets: TargetsMethods;
1830
- readonly destinations: DestinationsMethods;
1831
- readonly payments: PaymentsMethods;
1832
- readonly activity: ActivityMethods;
1833
- readonly offramp: OfframpMethods;
1834
- readonly paymentDocuments: PaymentDocumentsMethods;
1835
- }
1836
- //#endregion
1837
- //#region src/surface/contacts.d.ts
1838
- type ActorScopeRef = {
1839
- readonly kind: "account";
1840
- } | {
1841
- readonly kind: "org";
1842
- readonly orgId: string;
1843
- };
1844
- interface ActorProfile {
1845
- readonly actor: ActorScopeRef;
1846
- readonly displayName: string | null;
1847
- readonly email?: string;
1848
- readonly handle?: string;
1849
- }
1850
- /**
1851
- * How a counterparty entered the book, and what they are to the actor today.
1852
- *
1853
- * The first six values are the backend edge provenance VERBATIM (ADR-0022 R2);
1854
- * `employed` is projected from an open employment edge. The pre-substrate
1855
- * union published `requested` (a value that collapsed two directions) and
1856
- * `employee` (a value no backend path ever wrote).
1857
- */
1858
- type AddressBookRelationship = "paid" | "paidBy" | "invoiced" | "invoicedBy" | "member" | "manual" | "employed";
1859
- interface AddressBookEntry {
1860
- /**
1861
- * The counterparty's `PartyId`. It is stable: the id you read before a
1862
- * counterparty signs up is the id you read after (ADR-0022 R1). The old id
1863
- * was a derived string that changed at signup.
1864
- */
1865
- readonly id: PartyId;
1866
- readonly ref: Ref$1;
1867
- readonly label: string;
1868
- readonly relationship: readonly AddressBookRelationship[];
1869
- readonly hidden: boolean;
1870
- /** Epoch milliseconds of the most recent activity with this counterparty. */
1871
- readonly lastActivityAt: number;
1872
- }
1873
- interface AddressBookAddInput {
1874
- readonly ref: Ref$1;
1875
- readonly label?: string;
1876
- }
1877
- interface AddressBookLabelInput {
1878
- readonly entryId: PartyId;
1879
- readonly label: string;
1880
- }
1881
- interface AddressBookListInput {
1882
- readonly includeHidden?: boolean;
1883
- }
1884
- /**
1885
- * #1960 R02: the declared option type is the `InvocationControls` these methods
1886
- * have always forwarded to `deps.invocationControls`. Naming it lets a caller
1887
- * that captured one user attempt hand the same `correlation_id`/`journey_id` to
1888
- * the operation the attempt starts. `{ signal }` callers are unaffected.
1889
- */
1890
- interface AddressBookMethods {
1891
- list(input?: AddressBookListInput, options?: InvocationControls): Promise<CapxulResult<readonly AddressBookEntry[]>>;
1892
- get(entryId: PartyId, options?: InvocationControls): Promise<CapxulResult<AddressBookEntry | null>>;
1893
- add(input: AddressBookAddInput, options?: InvocationControls): Promise<CapxulResult<AddressBookEntry>>;
1894
- hide(entryId: PartyId, options?: InvocationControls): Promise<CapxulResult<AddressBookEntry>>;
1895
- unhide(entryId: PartyId, options?: InvocationControls): Promise<CapxulResult<AddressBookEntry>>;
1896
- label(input: AddressBookLabelInput, options?: InvocationControls): Promise<CapxulResult<AddressBookEntry>>;
1897
- }
1898
- interface ActorRequest {
1899
- readonly id: string;
1900
- readonly payer?: Ref$1;
1901
- readonly amount: PaymentMoney;
1902
- readonly reference: string;
1903
- readonly status: RequestStatus;
1904
- readonly expiresAt: number | null;
1905
- }
1906
- interface ActorRequestIssueInput {
1907
- readonly payer: Ref$1;
1908
- readonly amount: PaymentMoney;
1909
- readonly reference: string;
1910
- readonly memo?: string;
1911
- readonly expiresAt?: number;
1912
- }
1913
- /**
1914
- * The issuer's own requests. The options are the address book's
1915
- * `InvocationControls` (R07 #1965), so a caller that captured one browser
1916
- * attempt hands it to the operation that attempt started; `{ signal }` callers
1917
- * are unaffected.
1918
- */
1919
- interface ActorRequestsMethods {
1920
- issue(input: ActorRequestIssueInput, options?: InvocationControls): Promise<CapxulResult<ActorRequest>>;
1921
- list(options?: InvocationControls): Promise<CapxulResult<readonly ActorRequest[]>>;
1922
- get(requestId: string, options?: InvocationControls): Promise<CapxulResult<ActorRequest | null>>;
1923
- cancel(requestId: string, options?: InvocationControls): Promise<CapxulResult<ActorRequest>>;
1924
- }
1925
- interface InboxItem {
1926
- readonly id: string;
1927
- readonly issuer: Ref$1;
1928
- readonly amount: PaymentMoney;
1929
- readonly reference: string;
1930
- readonly status: InboxStatus;
1931
- }
1932
- interface InboxApproveInput {
1933
- readonly requestId: string;
1934
- readonly timing?: PaymentTiming;
1935
- readonly permissionId?: string;
1936
- }
1937
- /** The payer's own inbox. Its scope is the payer's, never the issuer's. */
1938
- interface InboxMethods {
1939
- list(options?: InvocationControls): Promise<CapxulResult<readonly InboxItem[]>>;
1940
- approve(input: InboxApproveInput, options?: InvocationControls): Promise<CapxulResult<Payment>>;
1941
- decline(requestId: string, options?: InvocationControls): Promise<CapxulResult<InboxItem>>;
1942
- }
1943
- interface ActorProfileMethods {
1944
- get(options?: {
1945
- readonly signal?: AbortSignal;
1946
- }): Promise<CapxulResult<ActorProfile>>;
1947
- /** R08 (#1966): accepts a captured attempt, exactly as the treasury read does. */
1948
- depositInstructions(options?: InvocationControls): Promise<CapxulResult<DepositInstructions>>;
1949
- }
1950
- interface ActorRelationshipMethods {
1951
- readonly addressBook: AddressBookMethods;
1952
- readonly requests: ActorRequestsMethods;
1953
- readonly inbox: InboxMethods;
1954
- readonly profile: ActorProfileMethods;
1955
- }
1956
- //#endregion
1957
- //#region src/surface/account.d.ts
1958
- type AccountStatus = {
1959
- readonly status: "notAuthenticated";
1960
- } | {
1961
- readonly status: "accountRequired";
1962
- readonly requirement: AccountRequirement;
1963
- readonly chainId: number;
1964
- } | {
1965
- readonly status: "accountProviderReady";
1966
- readonly requirement: AccountRequirement;
1967
- readonly chainId: number;
1968
- readonly source: AccountProviderSource;
1969
- readonly signerAddress: Address$1;
1970
- } | {
1971
- readonly status: "accountPrepared";
1972
- readonly requirement: AccountRequirement;
1973
- readonly account: SmartAccount;
1974
- readonly deployment: {
1975
- readonly status: "counterfactual";
1976
- };
1977
- } | {
1978
- readonly status: "accountReady";
1979
- readonly requirement: AccountRequirement;
1980
- readonly account: SmartAccount | null;
1981
- readonly deployment: {
1982
- readonly status: "counterfactual";
1983
- } | {
1984
- readonly status: "deployed";
1985
- readonly deployedAt: SmartAccount["deployedAt"];
1986
- };
1987
- };
1988
- /**
1989
- * Public consumer-facing surface (issue #159 · AC1+AC3). Exactly two
1990
- * methods. `provision` and `deploySafe` are intentionally NOT here —
1991
- * they are advanced/testing-only and will live on
1992
- * `client._internal.account` when sibling issue #161 lands. Per
1993
- * `packages/sdk/CONTEXT.md`, the narrowing is enforced at
1994
- * both the type level (the `keyof AccountMethods` extract is exactly
1995
- * `"getStatus" | "ensureReady"`) and at runtime (the bundle returned
1996
- * here has those two own-keys and nothing else).
1997
- *
1998
- * Per `packages/sdk/docs/architecture.md`, the
1999
- * `AccountStatus` discriminant includes variants that are returned only by
2000
- * `getStatus` (for example, `accountPrepared`). It is the durable
2001
- * shape consumers depend on. Sibling #161 will extend `ensureReady` to
2002
- * advance the ladder past `accountProviderReady` and from
2003
- * `accountPrepared` to `accountReady(deployed)`; until then, the type
2004
- * surface is stable and the runtime fixed-point is documented.
2005
- */
2006
- interface AccountMethods extends ActorRelationshipMethods {
2007
- /**
2008
- * Post-auth account setup lifecycle — domain vocabulary over the internal
2009
- * readiness ladder + provisioning lane (#356).
2010
- */
2011
- getLifecycle(): Promise<CapxulResult<AccountLifecycle>>;
2012
- /** Resume setup after `failed` and return the updated lifecycle snapshot. */
2013
- retrySetup(): Promise<CapxulResult<AccountLifecycle>>;
2014
- /**
2015
- * Internal advanced surface (#161 · AC1). Reserved for the rebuild's
2016
- * own `ensureReady` upward transitions and for testing harnesses;
2017
- * consumers MUST NOT depend on this in production. Tagged
2018
- * `@internal-use` per `.claude/rules/flow-internal-substrate.md`.
2019
- *
2020
- * @internal-use
2021
- */
2022
- readonly _internal: AccountInternalSurface;
2023
- }
2024
- /**
2025
- * Internal `provision` + `deploySafe` arms exposed at
2026
- * `client._internal.account` (#161). Each returns `Promise<CapxulResult<T>>`
2027
- * with the same error catalog the public methods use.
2028
- *
2029
- * @internal-use
2030
- */
2031
- interface AccountInternalSurface {
2032
- provision(): Promise<CapxulResult<SmartAccount>>;
2033
- deploySafe(observationSource?: unknown): Promise<CapxulResult<SmartAccount>>;
2034
- /** @internal-use Substrate readiness ladder — tests and e2e only. */
2035
- getStatus(): Promise<CapxulResult<AccountStatus>>;
2036
- /** @internal-use Lane runner — tests and e2e only. */
2037
- ensureReady(): Promise<CapxulResult<AccountStatus>>;
2038
- /** @internal-use Provisioning lane phase — tests and e2e only. */
2039
- getProvisioningPhase(): Promise<CapxulResult<ProvisioningPhase>>;
2040
- /** @internal-use Lane retry — tests and e2e only. */
2041
- retryProvisioning(): Promise<CapxulResult<ProvisioningPhase>>;
2042
- }
2043
- //#endregion
2044
- //#region src/surface/onboarding.d.ts
2045
- type PersonOnboardingInput = CompleteProfileInput;
2046
- type ReadyAccountLifecycle = Extract<AccountLifecycle, {
2047
- readonly status: "ready";
2048
- }>;
2049
- type CompletedPersonProfile = Omit<Profile$1, "displayName" | "handle"> & {
2050
- readonly displayName: string;
2051
- readonly handle: string;
2052
- };
2053
- interface PersonOnboarding {
2054
- readonly profile: CompletedPersonProfile;
2055
- readonly account: ReadyAccountLifecycle;
2056
- }
2057
- interface OrganizationOnboardingInput {
2058
- readonly name: string;
2059
- readonly handle: string;
2060
- readonly country: string;
2061
- readonly bio?: string;
2062
- readonly size?: string;
2063
- }
2064
- interface OrganizationOnboarding {
2065
- readonly organizationId: string;
2066
- }
2067
- interface OnboardingMethods {
2068
- completePerson(input: PersonOnboardingInput, options?: {
2069
- readonly signal?: AbortSignal;
2070
- }): Promise<CapxulResult<PersonOnboarding>>;
2071
- completeOrganization(input: OrganizationOnboardingInput, options?: {
2072
- readonly signal?: AbortSignal;
2073
- }): Promise<CapxulResult<OrganizationOnboarding>>;
2074
- }
2075
- //#endregion
2076
- //#region src/surface/accounts.d.ts
2077
- interface AccountsMethods {
2078
- read(options?: {
2079
- readonly signal?: AbortSignal;
2080
- }): Promise<CapxulResult<Account$1>>;
2081
- }
2082
- /**
2083
- * Faucet surface (dev-only). Deliberately OFF the public `AccountsMethods`;
2084
- * reachable only via `client._internal.accounts` (production-surface-policy.md).
2085
- * The reference CLI uses it only in the test environment. Consumers do not see `fund`.
2086
- */
2087
- interface AccountsFaucetMethods {
2088
- fund(amount: Money, options?: {
2089
- readonly signal?: AbortSignal;
2090
- }): Promise<CapxulResult<{
2091
- readonly txHash: string;
2092
- }>>;
2093
- }
2094
- //#endregion
2095
- //#region src/ports/org.d.ts
2096
- type CreateOrgPortInput = {
2097
- readonly input: CreateOrgInput;
2098
- };
2099
- type ReadOrgTreasuryInput = {
2100
- readonly orgId: OrgId;
2101
- };
2102
- type ListOrgsInput = Record<never, never>;
2103
- type ListOrgRolesInput = {
2104
- readonly orgId: OrgId;
2105
- };
2106
- type ListOrgMembersInput = {
2107
- readonly orgId: OrgId;
2108
- };
2109
- /**
2110
- * R06 (#1964): the program attaches the caller's captured attempt to this
2111
- * record through `copyInvocationObservation`, so the adapter forwards one
2112
- * observation context to the backend action that owns `org_invite_sent`. The
2113
- * carrier is a non-enumerable symbol and never becomes a wire field.
2114
- */
2115
- type InviteOrgMemberInput = {
2116
- readonly orgId: OrgId;
2117
- readonly input: InviteMemberInput;
2118
- };
2119
- type ResendOrgInviteTokenInput = {
2120
- readonly orgId: OrgId;
2121
- readonly email: string;
2122
- };
2123
- type DetectPendingOrgInvitationsInput = Record<never, never>;
2124
- type DetectPendingOrgInvitationsResult$1 = {
2125
- readonly matched: readonly OrgId[];
2126
- };
2127
- declare const OrgError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
2128
- readonly _tag: "OrgError";
2129
- } & Readonly<A>;
2130
- declare class OrgError extends OrgError_base<{
2131
- readonly operation: string;
2132
- readonly publicCode: CapxulErrorCode;
2133
- readonly publicError: CapxulError;
2134
- readonly cause: unknown;
2135
- readonly details?: CapxulErrorDetails;
2136
- }> {}
2137
- /** The live Organization port creates, reads, and lists Organizations. */
2138
- interface OrgPort {
2139
- createOrg(input: CreateOrgPortInput): Effect.Effect<OrgView, OrgError, never>;
2140
- readTreasury(input: ReadOrgTreasuryInput): Effect.Effect<Account$1, OrgError, never>;
2141
- listOrgs(input: ListOrgsInput): Effect.Effect<readonly OrgView[], OrgError, never>;
2142
- listRoles(input: ListOrgRolesInput): Effect.Effect<readonly RoleView[], OrgError, never>;
2143
- listMembers(input: ListOrgMembersInput): Effect.Effect<readonly MemberView[], OrgError, never>;
2144
- pendingMembers?(input: ListOrgMembersInput): Effect.Effect<readonly MemberView[], OrgError, never>;
2145
- inviteMember(input: InviteOrgMemberInput): Effect.Effect<MemberView, OrgError, never>;
2146
- resendInviteToken?(input: ResendOrgInviteTokenInput): Effect.Effect<MemberView, OrgError, never>;
2147
- detectAndAcceptPendingInvitations(input: DetectPendingOrgInvitationsInput): Effect.Effect<DetectPendingOrgInvitationsResult$1, OrgError, never>;
2148
- }
2149
- //#endregion
2150
- //#region src/surface/org-me.d.ts
2151
- /**
2152
- * One spend authority the Member holds. `limit` is the cap the payment gate
2153
- * enforces on a single payment — `null` means the Budget carries no cap. The
2154
- * amount still available under the cap is not part of this read and is not
2155
- * computable from it.
2156
- */
2157
- interface Budget {
2158
- readonly id: BudgetId;
2159
- /** Display name, taken from the Role the grant was motivated by. */
2160
- readonly label: string;
2161
- readonly limit: Money | null;
2162
- }
2163
- /**
2164
- * The caller's own standing in one Organization.
2165
- *
2166
- * `role` is `null` when the Role catalog cannot name the Member's Role — a
2167
- * label-less owner is tolerated (ADR-0017), so consumers must render an
2168
- * absent Role rather than invent one.
2169
- *
2170
- * `capabilities` are the two facts the backend actually enforces, and nothing
2171
- * else: managing people, and spending. Payroll and invoice approval are both
2172
- * spending, so both read `canSpend`.
2173
- */
2174
- interface OrgMe {
2175
- readonly role: {
2176
- readonly label: string;
2177
- } | null;
2178
- readonly capabilities: {
2179
- readonly canManagePeople: boolean;
2180
- readonly canSpend: boolean;
2181
- };
2182
- /** Named Budgets this Member can spend from. `canSpend` is the authority fact. */
2183
- readonly budgets: readonly Budget[];
2184
- readonly observedAt: number;
2185
- }
2186
- type OrgMeOptions = {
2187
- readonly signal?: AbortSignal;
2188
- };
2189
- type OrgMeMethod = (options?: OrgMeOptions) => Promise<CapxulResult<OrgMe>>;
2190
- //#endregion
2191
- //#region src/contract/permission.d.ts
2192
- interface PermissionReadResult {
2193
- readonly permissions: readonly Permission[];
2194
- readonly assignments: readonly PermissionAssignment[];
2195
- }
2196
- //#endregion
2197
- //#region src/surface/permissions.d.ts
2198
- type PermissionOptions = {
2199
- readonly signal?: AbortSignal;
2200
- };
2201
- type PermissionCreateInput = {
2202
- readonly requestKey: string;
2203
- readonly intent: PermissionIntent;
2204
- };
2205
- type PermissionChangeInput = PermissionCreateInput & {
2206
- readonly permissionId: string;
2207
- };
2208
- type PermissionAssignInput = {
2209
- readonly requestKey: string;
2210
- readonly permissionId: string;
2211
- readonly accountId: string;
2212
- /** Bind a staff activation to the invited Person at the backend authority boundary. */
2213
- readonly expectedMemberEmail?: string;
2214
- };
2215
- type PermissionRevokeInput = {
2216
- readonly requestKey: string;
2217
- readonly permissionAssignmentId: string;
2218
- };
2219
- type PermissionReplaceInput = {
2220
- readonly requestKey: string;
2221
- };
2222
- interface PermissionMethods {
2223
- create(input: PermissionCreateInput, options?: PermissionOptions): Promise<CapxulResult<SubmittedPermissionExecution>>;
2224
- change(input: PermissionChangeInput, options?: PermissionOptions): Promise<CapxulResult<SubmittedPermissionExecution>>;
2225
- assign(input: PermissionAssignInput, options?: PermissionOptions): Promise<CapxulResult<SubmittedPermissionExecution>>;
2226
- revoke(input: PermissionRevokeInput, options?: PermissionOptions): Promise<CapxulResult<SubmittedPermissionExecution>>;
2227
- replace(input: PermissionReplaceInput, options?: PermissionOptions): Promise<CapxulResult<SubmittedPermissionExecution>>;
2228
- list(options?: PermissionOptions): Promise<CapxulResult<PermissionReadResult>>;
2229
- get(permissionId: string, options?: PermissionOptions): Promise<CapxulResult<Permission | null>>;
2230
- }
2231
- //#endregion
2232
- //#region src/surface/organization-payments.d.ts
2233
- interface OrganizationPaymentItemInput {
2234
- readonly to: Ref$1;
2235
- readonly amount: PaymentMoney;
2236
- readonly externalAddressAcknowledged?: true;
2237
- readonly paymentType?: PaymentType;
2238
- readonly document?: AttachablePaymentDocumentEnvelopeV1;
2239
- }
2240
- interface OrganizationPaymentInput extends OrganizationPaymentItemInput {
2241
- readonly permissionId: string;
2242
- readonly lineage?: PaymentCommandLineage;
2243
- }
2244
- interface OrganizationPaymentBatchInput {
2245
- readonly permissionId: string;
2246
- readonly items: readonly OrganizationPaymentItemInput[];
2247
- readonly lineage?: PaymentCommandLineage;
2248
- }
2249
- interface OrganizationPaymentsMethods {
2250
- pay(input: OrganizationPaymentInput, options?: {
2251
- readonly signal?: AbortSignal;
2252
- }): Promise<CapxulResult<Payment>>;
2253
- payBatch(input: OrganizationPaymentBatchInput, options?: {
2254
- readonly signal?: AbortSignal;
2255
- }): Promise<CapxulResult<readonly Payment[]>>;
2256
- retry(paymentId: string, options?: {
2257
- readonly signal?: AbortSignal;
2258
- }): Promise<CapxulResult<readonly Payment[]>>;
2259
- }
2260
- //#endregion
2261
- //#region src/surface/payroll.d.ts
2262
- /** ADR-0022 R9: where the run stands on the shipped command lifecycle. */
2263
- type PayrollRunStatus = PayrollRunStatus$1;
2264
- /** One authorized payroll run. `total` is the sum of its items' nets. */
2265
- interface PayrollRun {
2266
- readonly id: PayrollRunId;
2267
- readonly status: PayrollRunStatus;
2268
- /** Epoch milliseconds. An instant run has `periodStart === periodEnd`. */
2269
- readonly periodStart: number;
2270
- readonly periodEnd: number;
2271
- readonly total: Money;
2272
- readonly recipientCount: number;
2273
- }
2274
- /**
2275
- * An organization's runs, newest first, with the month total beside them.
2276
- *
2277
- * The aggregate travels WITH the list because the backend computes it over
2278
- * every settled run in the calendar month while the list is one page. A
2279
- * consumer that summed `runs` would under-report an employer past the page.
2280
- */
2281
- interface PayrollRuns {
2282
- readonly runs: readonly PayrollRun[];
2283
- /** Σ net of the runs that SETTLED this calendar month — the "Paid This Month" fact. */
2284
- readonly settledThisMonth: Money;
2285
- }
2286
- /**
2287
- * One saved recipient on a group. `amount` is the employer's TYPED text, not
2288
- * minor units: a group is a draft the run composer prefills, and the run
2289
- * engine is the one place that parses an amount into money.
2290
- */
2291
- interface PayrollGroupMember {
2292
- /** The recipient's `PartyId` — the stable id (ADR-0022 R1), never an email. */
2293
- readonly partyId: string;
2294
- readonly amount: string;
2295
- readonly currency: CurrencyCode;
2296
- }
2297
- /** A saved roster the employer pays again. Server-held, so every member sees it. */
2298
- interface PayrollGroup {
2299
- readonly id: PayrollGroupId;
2300
- readonly name: string;
2301
- /** A stored display preference; the consumer narrows it to its own union. */
2302
- readonly tone: string;
2303
- readonly members: readonly PayrollGroupMember[];
2304
- }
2305
- /** What a rate is counted PER (ADR-0022 R7). The substrate holds no cadence. */
2306
- type PayrollTermsUnit = PayrollTermsUnit$1;
2307
- /**
2308
- * The rate in force for one open engagement, read at the moment of the call.
2309
- *
2310
- * Terms are versioned and insert-only, so this is a snapshot of a history: a
2311
- * raise inserts a later row and the next read states the new rate. The SDK
2312
- * derives NOTHING from it — ruling Q3 puts the prefill rule (which unit applies
2313
- * over which period) in the run composer, and Capxul computes no pay.
2314
- */
2315
- interface PayrollEngagementTerms {
2316
- /** The EMPLOYEE's `PartyId` — the key an `.Amounts` row is found by. */
2317
- readonly partyId: string;
2318
- /** Minor units counted in `decimals`; never a float. */
2319
- readonly rate: string;
2320
- readonly unit: PayrollTermsUnit;
2321
- readonly currency: CurrencyCode;
2322
- readonly decimals: number;
2323
- /** Epoch milliseconds — when this rate took effect. */
2324
- readonly effectiveFrom: number;
2325
- }
2326
- /** `id` absent creates a group; `id` present replaces that group in place. */
2327
- interface PayrollGroupInput {
2328
- readonly id?: PayrollGroupId;
2329
- readonly name: string;
2330
- readonly tone: string;
2331
- readonly members: readonly PayrollGroupMember[];
2332
- }
2333
- /**
2334
- * One person on one run. `net` is what they are paid; `gross` plus every
2335
- * adjustment must equal it (ADR-0022 R8) and the backend refuses a run where
2336
- * it does not. Both are minor-unit strings; an adjustment is signed.
2337
- */
2338
- interface PayrollRunItemInput {
2339
- /**
2340
- * The recipient. An email `Ref` or a party `Ref` in v1 — the backend refuses
2341
- * any other kind, because the recipient is what the party is DERIVED from.
2342
- */
2343
- readonly to: Ref$1;
2344
- /**
2345
- * The caller's ASSERTION of the party `to` resolves to, never the authority
2346
- * for it. The backend resolves `to` — an email through the invite path's
2347
- * person-party ensure, a party `Ref` through the same recipient resolution
2348
- * the batch runs — and refuses the run when this id is not that party, so
2349
- * the money, the `employed` edge and the payslip's employee can never name
2350
- * three different people.
2351
- */
2352
- readonly partyId: string;
2353
- readonly gross: string;
2354
- readonly net: string;
2355
- readonly adjustments: readonly {
2356
- readonly label: string;
2357
- readonly amount: string;
2358
- }[];
2359
- }
2360
- interface AuthorizeRunInput {
2361
- /** The Budget the run spends from. The caller selects it; nothing is picked for them. */
2362
- readonly permissionId: string;
2363
- /** Epoch milliseconds. An instant run passes `start === end` — the payslip renders the date. */
2364
- readonly period: {
2365
- readonly start: number;
2366
- readonly end: number;
2367
- };
2368
- readonly items: readonly PayrollRunItemInput[];
2369
- /**
2370
- * Supply one to reuse a key minted elsewhere. Left absent, the shipped
2371
- * fingerprint lifecycle derives it from this intent, so a retry of the same
2372
- * run replays the SAME command instead of paying twice.
2373
- */
2374
- readonly requestKey?: string;
2375
- }
2376
- /**
2377
- * R13 (#1968): the declared option type is the `InvocationControls` these
2378
- * methods have always forwarded to `deps.invocationControls` — the same naming
2379
- * R02 gave the address book. It lets a caller that captured one browser attempt
2380
- * hand that attempt's `correlation_id`/`journey_id` to the payroll operation it
2381
- * starts, so `ui_payroll_action_completed` and the durable group and run events
2382
- * share a correlation. `{ signal }` callers are unaffected.
2383
- */
2384
- type PayrollOptions = InvocationControls;
2385
- type AuthorizeRunOptions = PayrollOptions & {
2386
- /** Persist this SDK-allocated key before the first backend write. Reject to prevent execution. */
2387
- readonly onRequestKey?: (key: string) => void | Promise<void>;
2388
- /** A prior command is conclusively closed. The current failed result remains a failure. */
2389
- readonly onResolved?: (outcome: "failed" | "settled") => void | Promise<void>;
2390
- };
2391
- interface PayrollGroupsMethods {
2392
- list(options?: PayrollOptions): Promise<CapxulResult<readonly PayrollGroup[]>>;
2393
- save(input: PayrollGroupInput, options?: PayrollOptions): Promise<CapxulResult<PayrollGroup>>;
2394
- remove(id: PayrollGroupId, options?: PayrollOptions): Promise<CapxulResult<void>>;
2395
- }
2396
- interface PayrollMethods {
2397
- runs(options?: PayrollOptions): Promise<CapxulResult<PayrollRuns>>;
2398
- authorizeRun(input: AuthorizeRunInput, options?: AuthorizeRunOptions): Promise<CapxulResult<PayrollRun>>;
2399
- /** The active engagement terms of the org's employed people (ruling Q3). */
2400
- terms(options?: PayrollOptions): Promise<CapxulResult<readonly PayrollEngagementTerms[]>>;
2401
- readonly groups: PayrollGroupsMethods;
2402
- }
2403
- //#endregion
2404
- //#region src/surface/org.d.ts
2405
- /** The membership state for one Organization member. */
2406
- type MemberStatus = "pending" | "pending_safe" | "pending_grant" | "active" | "revoked" | "expired";
2407
- /** One Organization that the current user can access. */
2408
- type OrgView = {
2409
- readonly creationSource?: TesterKind;
2410
- readonly id: OrgId;
2411
- readonly name: string;
2412
- readonly handle: string;
2413
- readonly safeAddress: Address$1;
2414
- /** The viewing member's own role label within this org. */
2415
- readonly role: string;
2416
- /** The Organization treasury Account. */
2417
- readonly treasury: Account$1;
2418
- /** #1064: onboarding-collected description + size bucket; null when unset. */
2419
- readonly bio: string | null;
2420
- readonly size: string | null;
2421
- /** #1061 / ADR-0014: logo serving URL resolved at read time; null when unset. */
2422
- readonly logoUrl: string | null;
2423
- };
2424
- interface OrganizationAccount {
2425
- readonly id: string;
2426
- readonly address: string | null;
2427
- readonly balance: Money;
2428
- readonly available: Money;
2429
- }
2430
- interface OrganizationAuditLogItem {
2431
- readonly id: string;
2432
- readonly organizationId: string;
2433
- readonly action: string;
2434
- readonly actor: string | null;
2435
- readonly summary: string;
2436
- readonly createdAt: number;
2437
- readonly metadata?: Record<string, unknown>;
2438
- }
2439
- /**
2440
- * One Organization member. `personalSafeAddress` is the member identity key. It
2441
- * is `null` while the member is still `pending` (emailed into existence but not
2442
- * yet provisioned a personal Safe). `email` is the universal entry point.
2443
- */
2444
- type MemberView = {
2445
- readonly orgId: OrgId;
2446
- readonly email: Email;
2447
- readonly name: string | null;
2448
- /** Member identity key. `null` until the invitee provisions a Safe. */
2449
- readonly personalSafeAddress: Address$1 | null;
2450
- /** The member role label maps to the on-chain `roleKey`. */
2451
- readonly role: string;
2452
- readonly roleKey: RoleKey | null;
2453
- readonly status: MemberStatus;
2454
- readonly grantTxHash: string | null;
2455
- readonly revokeTxHash: string | null;
2456
- };
2457
- /** A role spend cap that Zodiac Roles and Allowance enforce on-chain. */
2458
- type RoleSpendCap = {
2459
- readonly perTx?: Money;
2460
- readonly perDay?: Money;
2461
- readonly toRecipients?: "anyone" | readonly Address$1[];
2462
- };
2463
- /** A Capxul Role definition. */
2464
- type RoleDefinition = {
2465
- readonly label: string;
2466
- readonly spend?: RoleSpendCap;
2467
- readonly canSpend?: boolean;
2468
- readonly canManageMembers?: boolean;
2469
- readonly canManageRoles?: boolean;
2470
- };
2471
- /**
2472
- * One role a member can be invited into on an Organization — a role that
2473
- * carries member-management authority. A Budget is granted, never offered as a
2474
- * job title (ADR-0024 R5), so it never appears here.
2475
- * `roleKey` is the on-chain bytes32 role key derived from the label. `definition`
2476
- * is the full Role DSL entry.
2477
- */
2478
- type RoleView = {
2479
- readonly orgId: OrgId;
2480
- readonly label: string;
2481
- readonly roleKey: RoleKey;
2482
- readonly definition: RoleDefinition;
2483
- };
2484
- /**
2485
- * The role template a new Organization is created from. Creation supports
2486
- * exactly one shape — a single founding owner (ADR-0024 R8). Any other value
2487
- * is REFUSED with `WRONG_STATE`.
2488
- */
2489
- type OrgTemplate = "Solo";
2490
- /**
2491
- * Input to `capxul.createOrg`. `name` is the display name.
2492
- * `handle` uses the shared global Handle grammar (`^[a-z0-9_-]{3,30}$`).
2493
- * `template` seeds the initial role set. `country` is stored without validation.
2494
- */
2495
- type CreateOrgInput = {
2496
- readonly name: string;
2497
- readonly handle: string;
2498
- readonly template: OrgTemplate;
2499
- readonly country?: string;
2500
- };
2501
- /**
2502
- * Input to `org(orgId).invite`. Email is the universal entry point.
2503
- * An address that is not yet a Capxul user creates a `pending`
2504
- * membership that resolves on sign-in. `role` is invitation metadata. It does
2505
- * not grant an on-chain Permission.
2506
- */
2507
- type InviteMemberInput = {
2508
- readonly email: string;
2509
- readonly role: string;
2510
- };
2511
- type ResendInviteTokenInput = {
2512
- readonly email: string;
2513
- };
2514
- /** Organization ids whose pending invitations match the current Account. */
2515
- type DetectPendingOrgInvitationsResult = {
2516
- readonly matched: readonly OrgId[];
2517
- };
2518
- /** Organization methods for one `orgId`. */
2519
- interface OrgScopedMethods extends ActorRelationshipMethods {
2520
- /**
2521
- * The caller's own standing in this Organization — Role, the two enforced
2522
- * capabilities, and the Budgets they can spend from. A caller who is not an
2523
- * active Member is refused, not reported as a Member without capabilities.
2524
- */
2525
- readonly me: OrgMeMethod;
2526
- /** Observe the durable, leak-safe lifecycle for this Organization only. */
2527
- getLifecycle(options?: {
2528
- readonly signal?: AbortSignal;
2529
- }): Promise<CapxulResult<OrgLifecycle>>;
2530
- /** Explicitly resume this Organization's durable setup lane. */
2531
- retrySetup(options?: {
2532
- readonly signal?: AbortSignal;
2533
- }): Promise<CapxulResult<OrgLifecycle>>;
2534
- /**
2535
- * The Organization treasury Account. R08 (#1966): the declared option type is
2536
- * the `InvocationControls` this surface already forwards, so a screen that
2537
- * captured one user attempt can hand the same `correlation_id`/`journey_id`
2538
- * to the read it starts. `{ signal }` callers are unaffected.
2539
- */
2540
- treasury(options?: InvocationControls): Promise<CapxulResult<Account$1>>;
2541
- readonly account: {
2542
- get(options?: InvocationControls): Promise<CapxulResult<OrganizationAccount>>;
2543
- };
2544
- members(options?: {
2545
- readonly signal?: AbortSignal;
2546
- }): Promise<CapxulResult<readonly MemberView[]>>;
2547
- roles(options?: {
2548
- readonly signal?: AbortSignal;
2549
- }): Promise<CapxulResult<readonly RoleView[]>>;
2550
- /**
2551
- * Invite a member by email. `options` is the browser attempt the caller
2552
- * captured before the person pressed the button (R06 #1964); it reaches the
2553
- * backend action unchanged, so the durable `org_invite_sent` and the later
2554
- * `org_invite_progressed` share the attempt's correlation. `{ signal }`
2555
- * callers are unaffected.
2556
- */
2557
- invite(input: InviteMemberInput, options?: InvocationControls): Promise<CapxulResult<MemberView>>;
2558
- /**
2559
- * Leak-safe Organization payment: execute through the payments engine with
2560
- * the selected receipt-verified Budget Permission
2561
- * and return a `Payment` (no `to: Address`, no `txHash`, no Safe / userOp
2562
- * internals). Writes a real `payments` row (`source:"org"`).
2563
- */
2564
- readonly permissions: PermissionMethods;
2565
- readonly payments: OrganizationPaymentsMethods;
2566
- /**
2567
- * Pay the team: the runs this Organization has authorized, the verb that
2568
- * authorizes one, and the saved groups a run is composed from (#1452).
2569
- * `authorizeRun` is a payment command like any other — same Budget gate,
2570
- * same signature, same request-key idempotency.
2571
- */
2572
- readonly payroll: PayrollMethods;
2573
- auditLog(options?: {
2574
- readonly signal?: AbortSignal;
2575
- }): Promise<CapxulResult<readonly OrganizationAuditLogItem[]>>;
2576
- }
2577
- type OrgsMethod = {
2578
- (options?: {
2579
- readonly signal?: AbortSignal;
2580
- }): Promise<CapxulResult<readonly OrgView[]>>;
2581
- detectAndAcceptPendingInvitations(options?: {
2582
- readonly signal?: AbortSignal;
2583
- }): Promise<CapxulResult<DetectPendingOrgInvitationsResult>>;
2584
- };
2585
- /**
2586
- * Top-level Org method bundle, exposed at `client.org` / `client.orgs` /
2587
- * `client.createOrg`. `org(orgId)` resolves the entity-scoped bundle.
2588
- */
2589
- interface OrgMethods {
2590
- createOrg(input: CreateOrgInput, options?: {
2591
- readonly signal?: AbortSignal;
2592
- }): Promise<CapxulResult<OrgView>>;
2593
- readonly orgs: OrgsMethod;
2594
- /** Resolve the entity-scoped bundle for a specific Organization. */
2595
- org(orgId: OrgId): OrgScopedMethods;
2596
- }
2597
- //#endregion
2598
- //#region src/surface/current-user.d.ts
2599
- interface CurrentUserContext {
2600
- readonly user: {
2601
- readonly id: string;
2602
- readonly email: string;
2603
- readonly displayName: string | null;
2604
- readonly handle: string | null;
2605
- readonly paymentLink: {
2606
- readonly handle: string;
2607
- readonly url: string;
2608
- } | null;
2609
- };
2610
- readonly personalAccount: {
2611
- readonly id: string;
2612
- readonly address: string | null;
2613
- } | null;
2614
- readonly organizations: readonly {
2615
- readonly id: string;
2616
- readonly name: string;
2617
- readonly handle: string;
2618
- readonly role: string;
2619
- readonly account: {
2620
- readonly id: string;
2621
- readonly address: string | null;
2622
- } | null;
2623
- }[];
2624
- }
2625
- interface CurrentUserMethods {
2626
- get(options?: {
2627
- readonly signal?: AbortSignal;
2628
- }): Promise<CapxulResult<CurrentUserContext>>;
2629
- }
2630
- //#endregion
2631
- //#region src/surface/media.d.ts
2632
- interface MediaMethods {
2633
- uploadImage(blob: Blob, options?: {
2634
- readonly signal?: AbortSignal;
2635
- }): Promise<CapxulResult<{
2636
- readonly storageId: string;
2637
- }>>;
2638
- setProfileImage(input: {
2639
- readonly storageId: string;
2640
- }, options?: {
2641
- readonly signal?: AbortSignal;
2642
- }): Promise<CapxulResult<{
2643
- readonly imageUrl: string | null;
2644
- }>>;
2645
- setOrgLogo(input: {
2646
- readonly orgId: string;
2647
- readonly storageId: string;
2648
- }, options?: {
2649
- readonly signal?: AbortSignal;
2650
- }): Promise<CapxulResult<{
2651
- readonly logoUrl: string | null;
2652
- }>>;
2653
- }
2654
- //#endregion
2655
- //#region src/contract/system.d.ts
2656
- /** What `system:healthObserved` answers. */
2657
- interface SystemHealth {
2658
- /** The nonce the caller sent, as the backend saw it. */
2659
- readonly nonce: string;
2660
- /** Deployment that answered, e.g. `api` for the Railway staging host. */
2661
- readonly deployment: string;
2662
- /** Backend clock at execution (epoch ms). */
2663
- readonly at: number;
2664
- }
2665
- //#endregion
2666
- //#region src/surface/system.d.ts
2667
- interface SystemMethods {
2668
- health(nonce: string, options?: {
2669
- readonly signal?: AbortSignal;
2670
- }): Promise<CapxulResult<SystemHealth>>;
2671
- }
2672
- //#endregion
2673
- //#region src/domain/money/primary-holding.d.ts
2674
- /**
2675
- * The one asset a screen shows when it can show only one. `symbol` is the
2676
- * TOKEN symbol the chain reported (`"USDX"`); `available.currency` is the
2677
- * consumer `CurrencyCode` that token stands for (`"USD"`). They are separate
2678
- * fields because they are separate facts.
2679
- */
2680
- interface Holding {
2681
- readonly id: string;
2682
- readonly symbol: string;
2683
- readonly available: Money;
2684
- }
2685
- //#endregion
2686
- //#region src/surface/holdings.d.ts
2687
- interface HoldingsMethods {
2688
- current(input?: {
2689
- readonly actor?: ActorReference;
2690
- }, options?: {
2691
- readonly signal?: AbortSignal;
2692
- }): Promise<CapxulResult<CurrentHoldings>>;
2693
- /**
2694
- * The designated display asset — the payable row holding the most money, or
2695
- * `null` when the snapshot carries no renderable row. Reads the same
2696
- * snapshot as `current` and picks from it; an empty answer is a value, not
2697
- * an error.
2698
- */
2699
- primary(input?: {
2700
- readonly actor?: ActorReference;
2701
- }, options?: {
2702
- readonly signal?: AbortSignal;
2703
- }): Promise<CapxulResult<Holding | null>>;
2704
- }
2705
- //#endregion
2706
- //#region src/surface/_shared/effect-actor-bridge.d.ts
2707
- type IdentityFacadeVerb = "requestCode" | "verifyCode" | "signOut" | "createOrganization" | "completePersonal" | "retry";
2708
- //#endregion
2709
- //#region src/surface/create-capxul-client.d.ts
2710
- type OrganizationSetupProofReceipt = {
2711
- readonly state: "submitted";
2712
- readonly orgId: string;
2713
- readonly chainId: number;
2714
- readonly signerEoa: string;
2715
- readonly founderAccount: string;
2716
- readonly organizationAccount: string;
2717
- readonly userOperationHash: string;
2718
- readonly submittedAt: number;
2719
- readonly attempt: number;
2720
- } | {
2721
- readonly state: "confirmed";
2722
- readonly orgId: string;
2723
- readonly chainId: number;
2724
- readonly signerEoa: string;
2725
- readonly founderAccount: string;
2726
- readonly organizationAccount: string;
2727
- readonly userOperationHash: string;
2728
- readonly submittedAt: number;
2729
- readonly attempt: number;
2730
- readonly confirmationTransactionHash: string;
2731
- readonly readyAt: number;
2732
- };
2733
- type OrganizationSetupProofMethods = {
2734
- readonly getProofReceipt: (orgId: string) => Promise<CapxulResult<OrganizationSetupProofReceipt | null>>;
2735
- };
2736
- type IdentityRuntimeSendResult = {
2737
- readonly ok: true;
2738
- readonly state: IdentityState;
2739
- } | {
2740
- readonly ok: false;
2741
- readonly refused: CapxulErrorCode;
2742
- readonly state: IdentityState;
2743
- };
2744
- type IdentityProfileDetails = {
2745
- readonly displayName: string;
2746
- readonly country: string;
2747
- readonly handle: string;
2748
- /**
2749
- * #1955: the storage id `useCapxulUploadImage` handed back on file pick, and
2750
- * the payout addresses the form collected. The create call carries them, so
2751
- * the backend binds the photo and writes the rails in the same durable step.
2752
- */
2753
- readonly imageStorageId?: string;
2754
- readonly payoutAddresses?: readonly PayoutAddress[];
2755
- };
2756
- interface IdentityRuntime {
2757
- readonly snapshot: () => IdentityState;
2758
- readonly subscribe: IdentityActor["subscribe"];
2759
- readonly subscribeTransitions: IdentityActor["subscribeTransitions"];
2760
- readonly send: (event: IdentityEvent, controls?: InvocationControls) => Promise<IdentityRuntimeSendResult>;
2761
- readonly completeProfile: (profile: IdentityProfileDetails, controls?: InvocationControls) => Promise<{
2762
- readonly ok: true;
2763
- } | {
2764
- readonly ok: false;
2765
- readonly reason: CapxulErrorCode;
2766
- readonly error?: CapxulError;
2767
- }>;
2768
- /** @internal Optional facade bridge for consumer test doubles. */
2769
- readonly runFacade?: <T>(verb: IdentityFacadeVerb, controls: InvocationControls | undefined, run: (controls: InvocationControls) => Promise<T>) => Promise<T>;
2770
- }
2771
- interface CapxulClient {
2772
- /** Stop this client's resources. Repeated calls share the same cleanup. */
2773
- close(): Promise<CapxulResult<void>>;
2774
- readonly auth: AuthMethods;
2775
- readonly smartAccount: SmartAccountMethods;
2776
- readonly identity: IdentityMethods;
2777
- readonly onboarding: OnboardingMethods;
2778
- /** `health(nonce)` returns the nonce from the configured deployment. Use it to verify backend liveness before sign-in. */
2779
- readonly system: SystemMethods;
2780
- /**
2781
- * Consumer-facing account readiness surface (issue #159 · AC1+AC3).
2782
- * Exactly `getStatus` + `ensureReady`; the `_internal.account`
2783
- * namespace with `provision` + `deploySafe` lands in sibling #161.
2784
- */
2785
- readonly account: AccountMethods;
2786
- /**
2787
- * Consumer-facing Account money read.
2788
- * Returns `{ balance, available }` as `Money` — never wei or token units.
2789
- */
2790
- readonly accounts: AccountsMethods;
2791
- readonly currentUser: CurrentUserMethods;
2792
- readonly me: MeMethods;
2793
- readonly targets: TargetsMethods;
2794
- readonly destinations: DestinationsMethods;
2795
- /**
2796
- * Direct Payments surface. `pay` records a validated-recipient
2797
- * payment; `list`/`get` read the ledger; `markSettled` is the host-execution
2798
- * callback.
2799
- */
2800
- readonly payments: PaymentsMethods;
2801
- readonly activity: ActivityMethods;
2802
- readonly holdings: HoldingsMethods;
2803
- readonly offramp: OfframpMethods;
2804
- /** Re-derive a Payment document EIP-712 hash. */
2805
- readonly paymentDocuments: PaymentDocumentsMethods;
2806
- /**
2807
- * Media surface (#1061 / ADR-0014): profile-image + org-logo upload/record.
2808
- */
2809
- readonly media: MediaMethods;
2810
- /**
2811
- * Organization domain surface.
2812
- * `createOrg(input)` creates an Org; `orgs()` lists the Orgs you belong to;
2813
- * `org(orgId)` resolves the entity-scoped bundle (treasury / members / roles,
2814
- * invitations, Permissions, and payments). Explicit entity scoping —
2815
- * It has no stateful active context.
2816
- */
2817
- readonly createOrg: OrgMethods["createOrg"];
2818
- readonly orgs: OrgMethods["orgs"];
2819
- readonly org: OrgMethods["org"];
2820
- /**
2821
- * Observable signer readiness (ACCESS #1520 · C12). `status()` reads the
2822
- * current `SignerStatus`. `subscribe` fires on every change and returns its
2823
- * own unsubscribe. Only the Openfort browser signer runs a readiness cycle.
2824
- * Every other signer reports `"unknown"`, so a gate that reads this fails
2825
- * closed. This is an observation surface, not a domain method: it performs no
2826
- * work and cannot fail, so it returns a value rather than a `CapxulResult`.
2827
- * It is not a public React surface — the action part that needs it reads this.
2828
- */
2829
- readonly signer: SignerStatusStore;
2830
- /**
2831
- * Internal identity integration runtime. It is consumed by
2832
- * `@capxul/sdk-react`, not exported as the actor substrate itself.
2833
- *
2834
- * @internal-use
2835
- */
2836
- readonly _internal: {
2837
- readonly identity: IdentityRuntime;
2838
- /**
2839
- * Resolved bootstrap for this client instance (chain, auth URLs, etc.).
2840
- * Off the public surface per production-surface-policy.md (#31).
2841
- */
2842
- readonly bootstrap: BootstrapResolution;
2843
- /**
2844
- * Dev-only faucet bundle (production-surface-policy.md). `fund` lives here,
2845
- * NOT on the public `client.accounts` surface.
2846
- */
2847
- readonly accounts: AccountsFaucetMethods;
2848
- /**
2849
- * Ponder read seam (P02). Present only when the client was built with an
2850
- * indexer origin, so every reader treats it as optional. Ponder holds what
2851
- * the chain said; Convex holds what the user meant. Reads here never run
2852
- * inside a write path and never wait for a finality tag.
2853
- */
2854
- readonly indexer?: IndexerReadPort;
2855
- /** Quarantined Reference-harness evidence; never a product Organization method. */
2856
- readonly organizationSetup: OrganizationSetupProofMethods;
2857
- /** Product telemetry projection for internal composition and test harnesses. */
2858
- readonly telemetry?: TelemetryPort;
2859
- readonly captureExternalAddressAcknowledged: (address: string, organizationId?: string) => void;
2860
- readonly close?: () => Promise<void>;
2861
- };
2862
- }
2863
- interface CreateCapxulClientInput {
2864
- /**
2865
- * The 10-port `FlowPorts` bundle. The identity actor uses its auth, clock,
2866
- * identity, smart-account, and telemetry seams internally; the remaining
2867
- * method bundles consume the same canonical port authorities.
2868
- */
2869
- readonly ports: FlowPorts;
2870
- /**
2871
- * Bootstrap resolution for this client instance. The factory closes over
2872
- * `bootstrap.chainId` internally; consumers do not pass a standalone
2873
- * chainId and no method boundary accepts one.
2874
- */
2875
- readonly bootstrap: BootstrapResolution;
2876
- /**
2877
- * Optional AuthCachePort. When omitted, `detectAuthCacheAdapter()` selects
2878
- * the appropriate per-environment adapter (Browser/FileSystem/InMemory).
2879
- */
2880
- readonly authCache?: AuthCachePort;
2881
- /**
2882
- * Optional AbortSignal reserved for callers that coordinate client lifetime.
2883
- */
2884
- readonly signal?: AbortSignal;
2885
- /**
2886
- * OTP TTL window in ms. Default 300_000 (5 min).
2887
- */
2888
- readonly otpTtlMs?: number;
2889
- /**
2890
- * Optional per-call timeout for invoked auth requests.
2891
- */
2892
- readonly invokeTimeoutMs?: number;
2893
- /**
2894
- * Init-time account readiness target (issue #159 · AC4). The factory
2895
- * closes over this so `client.account.{getStatus,ensureReady}` don't
2896
- * need to take a per-call requirement arg. REQUIRED — there is no
2897
- * hidden default. Consumers building flows that never need a smart
2898
- * account pass `"none"`; flows that want a counterfactual deposit
2899
- * address pass `"counterfactual"`; flows that need an on-chain Safe
2900
- * pass `"deployed"` (deploy path lands in sibling #161).
2901
- */
2902
- readonly requirement: AccountRequirement;
2903
- /**
2904
- * Consumer-held signer (backend-orchestrated-deploy.md). Required for
2905
- * `requirement: "deployed"` flows: `provision` reads `getAddress()` and the
2906
- * deploy path signs the backend's SafeOp digest via `signUserOpHash()`. The
2907
- * backend orchestrates build + gas + paymaster + submit — the client never
2908
- * holds an RPC URL, a gas-sponsorship policy, or a bundler.
2909
- */
2910
- readonly signer?: CapxulSigner;
2911
- /**
2912
- * Optional live Organization deployment. When supplied, `client.createOrg` and `org(id).treasury`
2913
- * run the live path (real deploy + on-chain balance); when omitted, the
2914
- * hermetic `$0` path runs (a fresh Org has no on-chain funds). The adapter
2915
- * that CONSTRUCTS this port (deployer key + RPC + authenticated Convex seam)
2916
- * is wired by the CLI deploy-stack; the factory only threads it through.
2917
- */
2918
- readonly orgDeploymentPort?: OrgPort;
2919
- /** Preferred Organization deployment data port. */
2920
- readonly orgPort?: OrgPort;
2921
- /**
2922
- * Internal Organization lifecycle capability. The Core SDK owns its
2923
- * choreography; production composition supplies the provider/backend steps.
2924
- */
2925
- readonly organizationSetup?: OrganizationSetupOps;
2926
- readonly orgDeploymentConfig?: SafeDeploymentConfig;
2927
- /** Internal runner carrying the composition root's logger/tracer references. */
2928
- readonly effectRunner?: {
2929
- readonly runSync: <A, E>(effect: Effect.Effect<A, E>) => A;
2930
- readonly runPromise: <A, E>(effect: Effect.Effect<A, E>) => Promise<A>;
2931
- };
2932
- }
2933
- //#endregion
2934
- //#region ../observability/src/engineering-delivery.d.ts
2935
- type MetricEntry = Metric.Metric.Metadata<unknown, unknown>;
2936
- interface CliEngineeringStats {
2937
- readonly records: number;
2938
- readonly reservedRecordBytes: number;
2939
- readonly peakRecords: number;
2940
- readonly peakReservedRecordBytes: number;
2941
- readonly activeRequests: number;
2942
- readonly requestBytes: number;
2943
- readonly peakRequests: number;
2944
- readonly peakRequestBytes: number;
2945
- /** Rejected records, fields, metric registrations and export attempts; not delivered-event count. */
2946
- readonly dropped: number;
2947
- readonly metricSeries: number;
2948
- }
2949
- /** Shared, closure-owned admission state; no queue or mutable counters are exposed. */
2950
- declare function makeCliEngineeringBudget(): Readonly<{
2951
- metricRegistry: Map<string, MetricEntry>;
2952
- emptyMetricRegistry: () => Map<string, MetricEntry>;
2953
- drop: () => void;
2954
- admitRecord(terminal: boolean): (() => void) | undefined;
2955
- admitRequest(bytes: number, terminal: boolean): (() => void) | undefined;
2956
- snapshot(): CliEngineeringStats;
2957
- }>;
2958
- type CliEngineeringBudget = ReturnType<typeof makeCliEngineeringBudget>;
2959
- //#endregion
2960
- //#region src/host-observability.d.ts
2961
- /** One host-owned observability module at the SDK consumer boundary. */
2962
- interface HostObservability {
2963
- readonly failures: ObservationAdapter;
2964
- readonly product: TelemetryPort;
2965
- }
2966
- interface PostHogObservabilityClient {
2967
- capture(event: string, properties?: Readonly<Record<string, unknown>>): unknown;
2968
- captureException?(exception: Error, properties?: Readonly<Record<string, unknown>>): unknown;
2969
- identify?(distinctId: string, properties?: Readonly<Record<string, unknown>>): unknown;
2970
- group?(groupType: string, groupKey: string, properties?: Readonly<Record<string, unknown>>): unknown;
2971
- reset?(): unknown;
2972
- }
2973
- interface PostHogObservabilityOptions {
2974
- /** Consent / kill-switch seam. Defaults to enabled. */
2975
- readonly enabled?: boolean | (() => boolean);
2976
- /** Omission preserves bootstrap engineering. False/throw closes the acquired runtime's collection. */
2977
- readonly engineeringEnabled?: boolean | (() => boolean);
2978
- /** Opt in to code/timing/correlation-only engineering exports. Omission preserves full safe diagnostics. */
2979
- readonly engineeringPrivacy?: "minimal";
2980
- /** Shared CLI-only admission and transport budget; omitted for other hosts. */
2981
- readonly engineeringDeliveryBudget?: CliEngineeringBudget;
2982
- /** Host environment stamped on every SDK-owned product event. */
2983
- readonly capxulEnv?: CapxulEnv;
2984
- /** Host-owned correlation context shared by product and failure delivery. */
2985
- readonly context?: ObservationContext | (() => ObservationContext | undefined);
2986
- }
2987
- /** Build the SDK's one host module around an already-initialized PostHog client. */
2988
- declare function postHogObservability(client: PostHogObservabilityClient | null | undefined, options?: PostHogObservabilityOptions): HostObservability;
2989
- //#endregion
2990
- //#region src/observation.d.ts
2991
- /** Host-owned correlation fields that are safe to attach to an SDK failure. */
2992
- interface ObservationContext extends Omit<WireObservationContext, "applicationId"> {}
2993
- /**
2994
- * The SDK-owned failure envelope delivered to observation adapters. It carries
2995
- * the real error message, the `CapxulError.details` object, the cause chain,
2996
- * and the stack. Secret material (keys, tokens, bearer headers) is masked;
2997
- * nothing else is withheld. Ruling 2026-09-01: an operator reading an issue
2998
- * needs the actual failure, not a placeholder.
2999
- */
3000
- interface SdkFailureObservation {
3001
- readonly exception: Error;
3002
- readonly sdkVersion: string;
3003
- readonly operation: string;
3004
- readonly errorKind: string;
3005
- /** Invocation snapshot; failure correlation wins over later host state. */
3006
- readonly context?: ObservationContext;
3007
- /** Enumerated discriminators from `CapxulError.details`, in property shape. */
3008
- readonly detail?: SdkFailureDetail;
3009
- /** The error's own message, secrets masked. */
3010
- readonly message?: string;
3011
- /** The full `CapxulError.details` object, secrets masked, JSON-safe. */
3012
- readonly details?: Readonly<Record<string, unknown>>;
3013
- /** Messages down the `cause` chain, outermost first, secrets masked. */
3014
- readonly causeChain?: readonly string[];
3015
- /** The original stack when the error had one, secrets masked. */
3016
- readonly stack?: string;
3017
- }
3018
- /**
3019
- * The PII-safe subset of `CapxulError.details`, already in PostHog property
3020
- * shape. `provider` + `provider_operation` name the failing dependency
3021
- * (`convex bootstrap`, `openfort configure`). `provider_error_source` names
3022
- * the owner of an allow-listed `provider_error_code`. `failure_mode` / `reason`
3023
- * are enumerated codes. `http_status` is the upstream status. Anything else on
3024
- * `details` (ids, field names, free text) is dropped at the boundary.
3025
- */
3026
- interface SdkFailureDetail {
3027
- readonly provider?: string;
3028
- readonly provider_operation?: string;
3029
- readonly provider_error_source?: string;
3030
- readonly provider_error_code?: string;
3031
- readonly target_host?: string;
3032
- readonly failure_mode?: string;
3033
- readonly reason?: string;
3034
- readonly http_status?: number;
3035
- readonly connection_id?: string;
3036
- readonly connection_count?: number;
3037
- readonly connection_retries?: number;
3038
- readonly close_code?: number;
3039
- readonly close_was_clean?: boolean;
3040
- readonly close_reason_present?: boolean;
3041
- readonly document_visibility?: string;
3042
- readonly navigator_online?: boolean;
3043
- readonly last_browser_event?: string;
3044
- readonly ms_since_browser_event?: number;
3045
- /** ADR-0023 R7: the chain cause, flat, same keys as every other producer. */
3046
- readonly chain_upstream?: string;
3047
- readonly chain_method?: string;
3048
- readonly chain_retryable?: boolean;
3049
- readonly chain_http_status?: number;
3050
- readonly chain_rpc_code?: number;
3051
- readonly chain_revert_name?: string;
3052
- readonly chain_revert_selector?: string;
3053
- readonly chain_revert_args?: Readonly<Record<string, string>>;
3054
- readonly chain_provider_message?: string;
3055
- /** #1818: the attempt sequence and the refusing upstream's headers, same bounds as the backend. */
3056
- readonly chain_attempts?: readonly SdkChainAttempt[];
3057
- readonly chain_response_headers?: Readonly<Record<string, string>>;
3058
- }
3059
- /** One upstream tried, flat: the `chain_attempts` entry shape on every producer's row. */
3060
- interface SdkChainAttempt {
3061
- readonly upstream: string;
3062
- readonly failure_mode: string;
3063
- readonly http_status?: number;
3064
- readonly rpc_code?: number;
3065
- readonly duration_ms: number;
3066
- }
3067
- type ObservationDelivery = void | PromiseLike<void>;
3068
- /**
3069
- * High-level host observation boundary. The SDK owns when each method is
3070
- * called; the host owns the destination client, consent, and delivery policy.
3071
- */
3072
- interface ObservationAdapter {
3073
- /**
3074
- * Optional read-only invocation context. Transport adapters snapshot it once
3075
- * at call start; implementations must not mutate global SDK state.
3076
- */
3077
- readonly resolveContext?: () => ObservationContext | undefined;
3078
- /** A method returned the SDK's typed `{ ok: false, error }` result. */
3079
- captureOperationFailure(failure: SdkFailureObservation): ObservationDelivery;
3080
- /** A method unexpectedly threw or rejected instead of returning a typed result. */
3081
- captureException(exception: SdkFailureObservation): ObservationDelivery;
3082
- }
3083
- /** Stable PostHog event used for typed failures that are expected product outcomes. */
3084
- declare const CAPXUL_SDK_EXPECTED_OUTCOME_EVENT = "capxul_sdk_expected_outcome";
3085
- //#endregion
3086
- //#region src/ports/diagnostic.d.ts
3087
- type DiagnosticDetail = Readonly<Record<string, unknown>>;
3088
- interface DiagnosticPort {
3089
- readonly trace: (scope: string, detail: DiagnosticDetail) => void;
3090
- }
3091
- //#endregion
3092
- //#region src/openfort/create-openfort-browser-signer.d.ts
3093
- interface OpenfortBrowserSignerOptions {
3094
- readonly diagnostic?: DiagnosticPort;
3095
- /** Testing seam below the existing one-retry recovery owner. */
3096
- readonly signUserOpHash?: ((hash: Parameters<CapxulSigner["signUserOpHash"]>[0], delegate: CapxulSigner["signUserOpHash"]) => ReturnType<CapxulSigner["signUserOpHash"]>) | undefined;
3097
- }
3098
- //#endregion
3099
- //#region src/production.d.ts
3100
- /**
3101
- * Consumer-facing `createCapxulClient` input (SDK DX public surface · #326).
3102
- * The publishable key is the primary input; bootstrap host, invoke timeout,
3103
- * runtime detection, and auth-cache selection are SDK-owned defaults.
3104
- */
3105
- interface CapxulClientInput {
3106
- readonly publishableKey: string;
3107
- /** Public Capxul bootstrap origin; defaults remain unchanged when omitted. */
3108
- readonly bootstrapBaseUrl?: string;
3109
- /**
3110
- * One host-owned product/failure observability module around the host's
3111
- * existing analytics client. Omit for zero host observation work.
3112
- */
3113
- readonly observability?: HostObservability;
3114
- /**
3115
- * Init-time account readiness target (issue #159 · AC4). Threaded into
3116
- * `assembleCapxulClient` so `client.account.{getStatus,ensureReady}` reflect
3117
- * the consumer's chosen requirement. Optional — defaults to `"none"` (SDK
3118
- * publish readiness · I3) so `createCapxulClient({ publishableKey })` works
3119
- * with no account lane.
3120
- */
3121
- readonly requirement?: AccountRequirement;
3122
- /**
3123
- * Consumer-held signer (backend-orchestrated-deploy.md). Required for
3124
- * `requirement: "deployed"` flows: `provision` reads `getAddress()` and the
3125
- * deploy path signs the backend's SafeOp digest via `signUserOpHash()`. The
3126
- * backend orchestrates build + gas + paymaster + submit — the client never
3127
- * holds an RPC URL, a gas-sponsorship policy, or a bundler.
3128
- */
3129
- readonly signer?: CapxulSigner;
3130
- }
3131
- /** Per-client signing controls; only the testing entry exposes these to consumers. */
3132
- interface ProductionSignerControls {
3133
- /** Final signing call. Address, readiness and session lifecycle retain their real owner. */
3134
- readonly signUserOpHash?: (hash: Parameters<CapxulSigner["signUserOpHash"]>[0], signer: CapxulSigner & {
3135
- readonly resetSession?: () => void;
3136
- }) => ReturnType<CapxulSigner["signUserOpHash"]>;
3137
- /** Embedded signing calls, including the existing recovery owner's single retry. */
3138
- readonly signEmbeddedUserOpHash?: OpenfortBrowserSignerOptions["signUserOpHash"];
3139
- }
3140
- //#endregion
3141
- export { OrganizationPaymentBatchInput as $, RequestStatus as $n, Destination as $t, OrgScopedMethods as A, Ref$1 as An, AddressBookAddInput as At, AuthorizeRunOptions as B, SmartAccountMethods as Bn, ActivityFilter as Bt, CurrentUserMethods as C, PaymentMoney as Cn, AccountMethods as Ct, MemberStatus as D, PaymentsMethods as Dn, ActorRequest as Dt, InviteMemberInput as E, PaymentType as En, ActorRelationshipMethods as Et, ResendInviteTokenInput as F, AccountLifecycle as Fn, InboxItem as Ft, PayrollGroupsMethods as G, ActorRef as Gn, ActivityPage as Gt, PayrollGroup as H, OrgLifecycle as Hn, ActivityKind as Ht, RoleDefinition as I, AccountSetupStep as In, InboxMethods as It, PayrollRun as J, SubmittedPermissionExecution as Jn, ActivitySummary as Jt, PayrollMethods as K, CurrentHoldings as Kn, ActivityRange as Kt, RoleSpendCap as L, isSettingUpLifecycle as Ln, ActivityAnnotation as Lt, OrgView as M, TargetReference as Mn, AddressBookLabelInput as Mt, OrganizationAccount as N, TargetsMethods as Nn, AddressBookMethods as Nt, MemberView as O, PaymentsPayInput as On, ActorRequestIssueInput as Ot, OrganizationAuditLogItem as P, fingerprintPaymentIntent as Pn, InboxApproveInput as Pt, PayrollTermsUnit as Q, PaymentStatus$1 as Qn, DepositInstructions as Qt, RoleView as R, CompleteProfileInput as Rn, ActivityAnnotationInput as Rt, CurrentUserContext as S, PaymentDocumentsMethods as Sn, ReadyAccountLifecycle as St, DetectPendingOrgInvitationsResult as T, PaymentTiming as Tn, ActorProfileMethods as Tt, PayrollGroupInput as U, OrgSetupStep as Un, ActivityListParams as Ut, PayrollEngagementTerms as V, AuthMethods as Vn, ActivityItem as Vt, PayrollGroupMember as W, PayoutAddress as Wn, ActivityMethods as Wt, PayrollRunStatus as X, PAYMENT_DIRECTIONS as Xn, ActivitySummaryTotal as Xt, PayrollRunItemInput as Y, InboxStatus as Yn, ActivitySummaryParams as Yt, PayrollRuns as Z, PAYMENT_STATUSES as Zn, ActorReference as Zt, HoldingsMethods as _, PaymentDirection as _n, OnboardingMethods as _t, ObservationContext as a, DestinationRemoveInput as an, IdentityEvent as ar, PermissionCreateInput as at, SystemHealth as b, PaymentDocumentRender as bn, PersonOnboarding as bt, HostObservability as c, MeMethods as cn, Readiness as cr, PermissionReplaceInput as ct, postHogObservability as d, OfframpMethods as dn, isClaimed as dr, Budget as dt, DestinationAddInput as en, TelemetryEvent as er, OrganizationPaymentInput as et, CapxulClient as f, OfframpQuote as fn, isRestoring as fr, OrgMe as ft, IdentityRuntimeSendResult as g, PaymentActivityEvidence as gn, CompletedPersonProfile as gt, IdentityRuntime as h, Payment as hn, AccountsMethods as ht, ObservationAdapter as i, DestinationRail as in, Destination$1 as ir, PermissionChangeInput as it, OrgTemplate as j, ResolvedTarget as jn, AddressBookEntry as jt, OrgMethods as k, RecipientResolution as kn, ActorRequestsMethods as kt, PostHogObservabilityClient as l, MeProfile as ln, StateLabel as lr, PermissionRevokeInput as lt, IdentityProfileDetails as m, OfframpStatus as mn, InvocationControls as mr, OrgMeOptions as mt, ProductionSignerControls as n, DestinationListInput as nn, TelemetryIdentifyInput as nr, OrganizationPaymentsMethods as nt, ObservationDelivery as o, DestinationsMethods as on, IdentityState as or, PermissionMethods as ot, CreateCapxulClientInput as p, OfframpQuoteInput as pn, IdentityTransition as pr, OrgMeMethod as pt, PayrollOptions as q, Permission as qn, ActivityReference as qt, CAPXUL_SDK_EXPECTED_OUTCOME_EVENT as r, DestinationPayload as rn, TelemetryPort as rr, PermissionAssignInput as rt, SdkFailureObservation as s, FinancialOpsMethods as sn, OrgLane as sr, PermissionOptions as st, CapxulClientInput as t, DestinationKind as tn, TelemetryGroupInput as tr, OrganizationPaymentItemInput as tt, PostHogObservabilityOptions as u, MovementActivityEvidence as un, destination as ur, PermissionReadResult as ut, Holding as v, PaymentDocumentKind as vn, OrganizationOnboarding as vt, CreateOrgInput as w, PaymentStatus as wn, ActorProfile as wt, MediaMethods as x, PaymentDocumentVerification as xn, PersonOnboardingInput as xt, SystemMethods as y, PaymentDocumentRef as yn, OrganizationOnboardingInput as yt, AuthorizeRunInput as z, IdentityMethods as zn, ActivityDetail as zt };