@capxul/sdk 1.0.0-alpha.9 → 1.2.0

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.
Files changed (32) hide show
  1. package/README.md +121 -6
  2. package/dist/{InMemoryAuthCacheAdapter-v5W-XB5M.mjs → InMemoryAuthCacheAdapter-Dr1sEd9y.mjs} +36 -16
  3. package/dist/InMemoryAuthCacheAdapter-Dr1sEd9y.mjs.map +1 -0
  4. package/dist/create-capxul-client-C7H5b68l.d.mts +2764 -0
  5. package/dist/create-capxul-client-C7H5b68l.d.mts.map +1 -0
  6. package/dist/create-capxul-client-DiqVIxsV.mjs +6980 -0
  7. package/dist/create-capxul-client-DiqVIxsV.mjs.map +1 -0
  8. package/dist/index.d.mts +119 -2020
  9. package/dist/index.d.mts.map +1 -1
  10. package/dist/index.mjs +2464 -6308
  11. package/dist/index.mjs.map +1 -1
  12. package/dist/node/index.d.mts +3 -6
  13. package/dist/node/index.d.mts.map +1 -1
  14. package/dist/node/index.mjs +27 -27
  15. package/dist/node/index.mjs.map +1 -1
  16. package/dist/signer-CJT0pPiO.d.mts +301 -0
  17. package/dist/signer-CJT0pPiO.d.mts.map +1 -0
  18. package/dist/testing/index.d.mts +54 -0
  19. package/dist/testing/index.d.mts.map +1 -0
  20. package/dist/testing/index.mjs +1068 -0
  21. package/dist/testing/index.mjs.map +1 -0
  22. package/package.json +17 -18
  23. package/dist/InMemoryAuthCacheAdapter-v5W-XB5M.mjs.map +0 -1
  24. package/dist/index-CTXgQ_xR.d.mts +0 -158
  25. package/dist/index-CTXgQ_xR.d.mts.map +0 -1
  26. package/dist/ports/safe-deployment.d.mts +0 -2
  27. package/dist/ports/safe-deployment.mjs +0 -38
  28. package/dist/ports/safe-deployment.mjs.map +0 -1
  29. package/dist/safe-deployment-D3k9yndM.d.mts +0 -136
  30. package/dist/safe-deployment-D3k9yndM.d.mts.map +0 -1
  31. package/dist/signer-DqDtJU1l.d.mts +0 -145
  32. package/dist/signer-DqDtJU1l.d.mts.map +0 -1
@@ -0,0 +1,2764 @@
1
+ import { A as CurrencyCode, B as RunId, C as AnonymousDistinctId, D as BlockNumber, E as AuthUserId, F as Money, G as TxHash, H as SmartAccount, I as OrgId, J as CapxulError, L as Profile, M as DurationMs, N as Email, O as ChainId, P as EpochMs, Q as FailureMode, R as PublishableKey, S as AllowedOrigin, T as AuthSession, U as SubAccount, V as SessionToken, W as SubAccountId, X as CapxulErrorDetails, Y as CapxulErrorCode, Z as Failure, b as AccountId, d as CapxulResult, f as Profile$1, g as AuthCachePort, j as DocumentHash, k as CountryCode, m as SmartAccount$1, n as CapxulSigner, o as AccountProviderSource, p as Session$1, s as AccountRequirement, v as CachedJwt, w as AppId, x as Address, y as Account$1, z as RoleKey } from "./signer-CJT0pPiO.mjs";
2
+ import { Hex } from "viem";
3
+ import { Context, Effect, Layer, Schema, Scope, Tracer } from "effect";
4
+ import { FunctionReference } from "convex/server";
5
+
6
+ //#region src/domain/machine/shell.d.ts
7
+ declare const INVOCATION_PARENT_SPAN: unique symbol;
8
+ interface InvocationControls {
9
+ readonly signal?: AbortSignal;
10
+ readonly timeoutMs?: number;
11
+ readonly deadlineMs?: number;
12
+ readonly correlation_id?: string;
13
+ readonly journey_id?: string;
14
+ /** @internal Opaque in-process trace parent; symbols never enter wire or P3 records. */
15
+ readonly [INVOCATION_PARENT_SPAN]?: Tracer.AnySpan;
16
+ }
17
+ type RecordBase = {
18
+ readonly machine: string;
19
+ readonly event: string;
20
+ readonly slot: string;
21
+ readonly epoch: number;
22
+ readonly duration_ms: number;
23
+ readonly correlation_id?: string;
24
+ readonly journey_id?: string;
25
+ };
26
+ type IdentityTransition = (RecordBase & {
27
+ readonly outcome: "applied";
28
+ readonly from: string;
29
+ readonly to: string;
30
+ readonly refusal_code?: never;
31
+ readonly error_code?: never;
32
+ }) | (RecordBase & {
33
+ readonly outcome: "refused";
34
+ readonly state: string;
35
+ readonly refusal_code: CapxulErrorCode;
36
+ readonly error_code?: never;
37
+ }) | (RecordBase & {
38
+ readonly outcome: "failed" | "cancelled";
39
+ readonly state: string;
40
+ readonly error_code: CapxulErrorCode;
41
+ readonly refusal_code?: never;
42
+ });
43
+ declare class ActorFailure<Reason extends CapxulErrorCode> extends Error {
44
+ readonly reason: Reason;
45
+ readonly machine: string;
46
+ readonly state: string;
47
+ readonly event: string;
48
+ readonly details?: Readonly<Record<string, unknown>> | undefined;
49
+ readonly _tag = "ActorFailure";
50
+ constructor(reason: Reason, machine: string, state: string, event: string, details?: Readonly<Record<string, unknown>> | undefined);
51
+ }
52
+ interface Actor<S, Pub, Reason extends CapxulErrorCode> {
53
+ readonly ask: (event: Pub, controls?: InvocationControls) => Effect.Effect<S, ActorFailure<Reason | CapxulErrorCode>>;
54
+ readonly tell: (event: Pub, controls?: InvocationControls) => Effect.Effect<void, ActorFailure<Reason | CapxulErrorCode>>;
55
+ readonly snapshot: () => S;
56
+ readonly subscribe: (observer: (state: S) => void) => () => void;
57
+ readonly subscribeTransitions: (observer: (record: IdentityTransition) => void) => () => void;
58
+ }
59
+ //#endregion
60
+ //#region src/domain/identity/model.d.ts
61
+ type RefusalReason = "WRONG_STATE" | "INVALID_INPUT" | "OTP_EXPIRED" | "SIGNER_REJECTED";
62
+ interface Session {
63
+ readonly email: string;
64
+ readonly authUserId: string;
65
+ }
66
+ /** the pre-S1 account lane — PRD #462: wallet→identity→provision is counterfactual
67
+ * and signerless; `deploy` is the separate claim step that needs a signer. */
68
+ type AccountStep = "wallet" | "identity" | "provision" | "deploy";
69
+ /** org-lifecycle.ts:7-11, verbatim. */
70
+ type OrgStep = "preparingFounderAccount" | "awaitingFounderAuthorization" | "submittingBootstrap" | "confirmingBootstrap";
71
+ interface OrgDraft {
72
+ readonly name: string;
73
+ readonly handle: string;
74
+ readonly country: string;
75
+ }
76
+ /** Full one-shot coordinator input. Only {@link OrgDraft} is retained in IdentityState. */
77
+ interface OrgSubmissionDraft extends OrgDraft {
78
+ readonly bio?: string;
79
+ readonly size?: string;
80
+ }
81
+ /** The org lane, keyed by the active orgId — which does not exist yet while the
82
+ * FIRST DURABLE ORG WRITE is in flight, hence `creating` carrying only a draft. */
83
+ type OrgLane = {
84
+ readonly at: "creating";
85
+ readonly draft: OrgDraft;
86
+ } | {
87
+ readonly at: "loading";
88
+ readonly orgId: string;
89
+ } | {
90
+ readonly at: "settingUp";
91
+ readonly orgId: string;
92
+ readonly step: OrgStep;
93
+ } | {
94
+ readonly at: "ready";
95
+ readonly orgId: string;
96
+ } | {
97
+ readonly at: "failed";
98
+ readonly orgId: string | null;
99
+ readonly step: OrgStep;
100
+ readonly failure: Failure;
101
+ readonly retryable: boolean;
102
+ };
103
+ /**
104
+ * Personal-account readiness — the ONLY pre-org readiness truth (#1049 #1051).
105
+ * `claimed` is the single variant with an `org` field: the map's ordering
106
+ * `Account deployed+claimed → first durable Organization write` is expressed by
107
+ * the absence of that field everywhere else, not by a guard someone can forget.
108
+ */
109
+ type Readiness = {
110
+ readonly at: "unknown";
111
+ } | {
112
+ readonly at: "deriving";
113
+ readonly step: AccountStep;
114
+ } | {
115
+ readonly at: "counterfactual";
116
+ readonly address: string;
117
+ } | {
118
+ readonly at: "claiming";
119
+ readonly address: string;
120
+ } | {
121
+ readonly at: "claimed";
122
+ readonly address: string;
123
+ readonly org: OrgLane | null;
124
+ } | {
125
+ readonly at: "failed";
126
+ readonly step: AccountStep;
127
+ readonly failure: Failure;
128
+ readonly retryable: boolean;
129
+ };
130
+ type IdentityState = {
131
+ readonly phase: "signed_out";
132
+ } | {
133
+ readonly phase: "otp_sending";
134
+ readonly email: string;
135
+ } | {
136
+ readonly phase: "otp_pending";
137
+ readonly email: string;
138
+ readonly requestedAt: number;
139
+ } | {
140
+ readonly phase: "otp_verifying";
141
+ readonly email: string;
142
+ readonly requestedAt: number;
143
+ } | {
144
+ readonly phase: "authenticated";
145
+ readonly session: Session;
146
+ readonly profileComplete: boolean;
147
+ readonly account: Readiness;
148
+ } | {
149
+ readonly phase: "signing_out";
150
+ readonly session: Session | null;
151
+ } | {
152
+ readonly phase: "faulted";
153
+ readonly failure: Failure;
154
+ /** Non-null exactly when an OTP entry is resumable — the incumbent's
155
+ * `email !== null && otpRequestedAt !== null` pair (the pre-S1 auth machine),
156
+ * made structural. */
157
+ readonly resume: {
158
+ readonly email: string;
159
+ readonly requestedAt: number;
160
+ } | null;
161
+ };
162
+ declare const STATE_LABELS: readonly ["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"];
163
+ type StateLabel = (typeof STATE_LABELS)[number];
164
+ type IdentityEvent = {
165
+ readonly _tag: "RequestOtp";
166
+ readonly email: string;
167
+ } | {
168
+ readonly _tag: "VerifyOtp";
169
+ readonly email: string;
170
+ readonly otp: string;
171
+ readonly now: number;
172
+ } | {
173
+ readonly _tag: "ReadSession";
174
+ } | {
175
+ readonly _tag: "SignOut";
176
+ } | {
177
+ readonly _tag: "RestoreSession";
178
+ readonly session: Session;
179
+ readonly profileComplete: boolean;
180
+ } | {
181
+ readonly _tag: "ResumeOtpEntry";
182
+ readonly now: number;
183
+ } | {
184
+ readonly _tag: "Reset";
185
+ } | {
186
+ readonly _tag: "EnsureAccount";
187
+ } | {
188
+ readonly _tag: "ClaimAccount";
189
+ } | {
190
+ readonly _tag: "RetryAccount";
191
+ } | {
192
+ readonly _tag: "CreateOrganization";
193
+ readonly draft: OrgSubmissionDraft;
194
+ } | {
195
+ readonly _tag: "AttachOrganization";
196
+ readonly orgId: string;
197
+ } | {
198
+ readonly _tag: "RetryOrganization";
199
+ } | {
200
+ readonly _tag: "LeaveOrganization";
201
+ };
202
+ type Destination$1 = {
203
+ readonly to: "home";
204
+ } | {
205
+ readonly to: "selectUserType";
206
+ } | {
207
+ readonly to: "provisioning";
208
+ readonly scope: "personal";
209
+ } | {
210
+ readonly to: "provisioning";
211
+ readonly scope: "organization";
212
+ readonly orgId: string | null;
213
+ } | {
214
+ readonly to: "dashboardPersonal";
215
+ } | {
216
+ readonly to: "dashboardOrganization";
217
+ readonly orgId: string;
218
+ };
219
+ /**
220
+ * The post-auth destination and provisioning lane merge as one total switch
221
+ * over the nest. "An active journey outranks default
222
+ * routing; org-list contents never choose a destination" holds by construction:
223
+ * there is no org list in the state, only the ONE active lane.
224
+ */
225
+ declare const destination: (state: IdentityState) => Destination$1 | null;
226
+ //#endregion
227
+ //#region src/ports/auth-client.d.ts
228
+ type AuthClientOperationOptions = {
229
+ readonly signal?: AbortSignal;
230
+ };
231
+ type SendOtpInput = {
232
+ readonly email: Email;
233
+ };
234
+ type CanSendOtpInput = {
235
+ readonly email: Email;
236
+ };
237
+ type CanSendOtpStatus = {
238
+ readonly allowed: boolean;
239
+ readonly cooldownMs: DurationMs;
240
+ };
241
+ type VerifyOtpInput = {
242
+ readonly email: Email;
243
+ readonly otp: string;
244
+ };
245
+ type GetConvexJwtOptions = AuthClientOperationOptions & {
246
+ readonly forceRefresh?: boolean;
247
+ };
248
+ declare const AuthClientError_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 & {
249
+ readonly _tag: "AuthClientError";
250
+ } & Readonly<A>;
251
+ declare class AuthClientError extends AuthClientError_base<{
252
+ readonly operation: string;
253
+ readonly kind: string;
254
+ readonly cause: unknown;
255
+ }> {}
256
+ interface AuthClientPort {
257
+ canSendOtp(input: CanSendOtpInput, options?: AuthClientOperationOptions): Effect.Effect<CanSendOtpStatus, AuthClientError>;
258
+ sendOtp(input: SendOtpInput, options?: AuthClientOperationOptions): Effect.Effect<void, AuthClientError>;
259
+ verifyOtp(input: VerifyOtpInput, options?: AuthClientOperationOptions): Effect.Effect<AuthSession, AuthClientError>;
260
+ getSession(options?: AuthClientOperationOptions): Effect.Effect<AuthSession | null, AuthClientError>;
261
+ signOut(options?: AuthClientOperationOptions): Effect.Effect<void, AuthClientError>;
262
+ /**
263
+ * Fetches a Convex-aud JWT from `/api/auth/convex/token` (W7). Server mints
264
+ * a fresh JWT on every call per Probe A's 2026-05-19 finding (RS256, 900 s
265
+ * lifetime, `iss = <site-url>`, `aud = convex`). The caller (the SDK's
266
+ * `tokenProvider` wired into ConvexCallPort) is responsible for the
267
+ * `exp - 30s` proactive cache + `forceRefresh` callback handshake.
268
+ */
269
+ getConvexJwt(options?: GetConvexJwtOptions): Effect.Effect<CachedJwt, AuthClientError>;
270
+ }
271
+ //#endregion
272
+ //#region src/ports/clock.d.ts
273
+ interface ClockPort {
274
+ readonly now: Effect.Effect<EpochMs, ClockError>;
275
+ readonly sleep: (duration: DurationMs) => Effect.Effect<void, ClockError>;
276
+ }
277
+ declare const ClockError_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 & {
278
+ readonly _tag: "ClockError";
279
+ } & Readonly<A>;
280
+ declare class ClockError extends ClockError_base<{
281
+ readonly operation: "now" | "sleep" | "initialize";
282
+ readonly cause: unknown;
283
+ }> {}
284
+ //#endregion
285
+ //#region ../observability/src/telemetry-port.d.ts
286
+ /**
287
+ * Context for reporting handled errors via `reportHandledError`.
288
+ * Carries structured metadata extracted from the error context.
289
+ */
290
+ interface HandledErrorReportContext {
291
+ readonly layer?: string;
292
+ readonly operation?: string;
293
+ readonly failure_mode?: FailureMode;
294
+ readonly provider?: string;
295
+ }
296
+ /**
297
+ * Canonical TelemetryPort interface. Every adapter (production, test, in-memory)
298
+ * implements this contract. All methods return `Effect<void, never>` —
299
+ * fire-and-forget, defects are caught and traced.
300
+ */
301
+ interface TelemetryPort {
302
+ readonly emit: (event: TelemetryEvent) => Effect.Effect<void, never>;
303
+ readonly identify: (input: TelemetryIdentifyInput) => Effect.Effect<void, never>;
304
+ readonly group: (input: TelemetryGroupInput) => Effect.Effect<void, never>;
305
+ readonly reset: () => Effect.Effect<void, never>;
306
+ readonly reportHandledError?: (error: CapxulError, context?: HandledErrorReportContext) => Effect.Effect<void, never>;
307
+ }
308
+ //#endregion
309
+ //#region ../observability/src/index.d.ts
310
+ declare const TELEMETRY_EVENT_NAMES: readonly ["auth_otp_requested", "auth_otp_delivered", "auth_otp_expired", "auth_verified", "auth_failed", "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", "account_balance_read", "account_balance_failed", "faucet_requested", "faucet_confirmed", "faucet_failed", "subaccount_created", "subaccount_renamed", "subaccount_deleted", "subaccount_op_failed", "transfer_requested", "transfer_backend_received", "transfer_confirmed", "transfer_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_role_granted", "org_member_active", "org_member_removed", "org_invite_expired", "org_role_grant_failed", "payment_requested", "payment_resolved", "payment_document_attached", "payment_submitted", "payment_settled", "payment_claimed", "payment_cancelled", "payment_redirected", "payment_failed", "stream_created", "stream_claimed", "stream_cancelled", "stream_completed", "stream_failed", "withdrawal_requested", "withdrawal_submitted", "withdrawal_settled", "withdrawal_failed"];
311
+ type TelemetryEventName = (typeof TELEMETRY_EVENT_NAMES)[number];
312
+ type TelemetryProps = Record<string, unknown>;
313
+ type TelemetryEvent = {
314
+ readonly name: TelemetryEventName;
315
+ readonly props?: TelemetryProps | undefined;
316
+ };
317
+ /**
318
+ * Environment discriminator (ADR-0020 A1 amendment, 2026-08-07). PostHog
319
+ * project 368736 is the SINGLE sink for every environment, so `capxul_env` —
320
+ * not project isolation — is what keeps a production surface from reading dev
321
+ * traffic. It is REQUIRED on every catalog event and every synced artifact
322
+ * filters on it.
323
+ *
324
+ * `unknown` is a defect marker, not an environment: it means a producer
325
+ * reached the transport without declaring where it runs. It is in the union so
326
+ * the property is never ABSENT (an absent property is invisible to a filter,
327
+ * a present `unknown` is loud), and sync v2 never synthesizes an artifact for
328
+ * it.
329
+ */
330
+ declare const CAPXUL_ENVS: readonly ["development", "e2e", "staging", "production", "unknown"];
331
+ type CapxulEnv = (typeof CAPXUL_ENVS)[number];
332
+ interface TelemetryIdentifyInput {
333
+ readonly distinctId: string;
334
+ readonly anonDistinctId?: AnonymousDistinctId;
335
+ readonly traits?: TelemetryProps;
336
+ readonly properties?: TelemetryProps;
337
+ }
338
+ interface TelemetryGroupInput {
339
+ readonly groupType: string;
340
+ readonly groupKey: string;
341
+ readonly properties?: TelemetryProps;
342
+ }
343
+ //#endregion
344
+ //#region src/ports/bootstrap.d.ts
345
+ type BootstrapInput = {
346
+ readonly publishableKey: PublishableKey;
347
+ /**
348
+ * Browser callers send the App origin so bootstrap can enforce the
349
+ * publishable-key allowlist. Node/server callers may omit it; the backend
350
+ * only applies the origin allowlist when an origin is present.
351
+ */
352
+ readonly origin?: AllowedOrigin;
353
+ };
354
+ type BootstrapResolution = {
355
+ readonly applicationId: AppId;
356
+ readonly chainId: ChainId;
357
+ /**
358
+ * SDK-handshake session token — distinct from the user-auth `AuthSession`
359
+ * token issued by `AuthClientPort`. Both use the `SessionToken` brand for
360
+ * opaque-string discipline; the issuance source distinguishes them.
361
+ */
362
+ readonly sessionToken: SessionToken;
363
+ readonly issuedAt: EpochMs;
364
+ readonly expiresIn: DurationMs;
365
+ readonly authBaseUrl: string;
366
+ readonly convexUrl: string;
367
+ readonly siteBaseUrl: string;
368
+ readonly openfortPublishableKey: string;
369
+ readonly shieldPublishableKey: string;
370
+ };
371
+ type BootstrapErrorKind = "notAuthenticated" | "network" | "provider" | "malformedBody" | "invalidInput" | "rateLimited";
372
+ 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 & {
373
+ readonly _tag: "BootstrapError";
374
+ } & Readonly<A>;
375
+ declare class BootstrapError extends BootstrapError_base<{
376
+ readonly operation: "resolve";
377
+ readonly kind: BootstrapErrorKind;
378
+ readonly publicCode: CapxulErrorCode;
379
+ readonly cause: unknown;
380
+ readonly details?: CapxulErrorDetails;
381
+ }> {}
382
+ interface BootstrapPort {
383
+ readonly resolve: (input: BootstrapInput) => Effect.Effect<BootstrapResolution, BootstrapError>;
384
+ }
385
+ //#endregion
386
+ //#region src/ports/convex-call.d.ts
387
+ /**
388
+ * Canonical teardown handle for substrate-level reactive callbacks.
389
+ *
390
+ * Calling it stops the subscription; no further snapshots will be delivered
391
+ * to the callback after the first invocation. Calling more than once is a
392
+ * no-op (idempotent).
393
+ *
394
+ * @internal-use
395
+ */
396
+ type Unsubscribe = () => void;
397
+ /**
398
+ * Snapshot is the substrate discriminated union for reactive callbacks over
399
+ * `ConvexCallPort.subscribe`. The public SDK surface is imperative
400
+ * (`Promise<CapxulResult>`).
401
+ *
402
+ * - `loading` · initial state before any value arrives from the substrate
403
+ * - `ok` · a successful snapshot carrying `value`
404
+ * - `error` · a failed snapshot carrying a typed error (defaults to
405
+ * `CapxulError`)
406
+ *
407
+ * The substrate guarantees the first snapshot is `loading` (CC8 in the
408
+ * `ConvexCallPort` contract); subsequent snapshots carry `ok` or `error`
409
+ * per the underlying transport.
410
+ *
411
+ * Per ARCH-LOCK-1 (`docs/decisions/stage-4-reactivity-pivot.html`), domain
412
+ * ports do not expose reactive callback methods — this pair lives on the
413
+ * substrate port that owns `subscribe` (#1145 re-homed it from the former
414
+ * `ports/subscription.ts`, which was never a port).
415
+ *
416
+ * @internal-use
417
+ */
418
+ type Snapshot<T, E = CapxulError> = {
419
+ readonly status: "loading";
420
+ } | {
421
+ readonly status: "ok";
422
+ readonly value: T;
423
+ } | {
424
+ readonly status: "error";
425
+ readonly error: E;
426
+ };
427
+ 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 & {
428
+ readonly _tag: "ConvexCallError";
429
+ } & Readonly<A>;
430
+ declare class ConvexCallError extends ConvexCallError_base<{
431
+ readonly operation: string;
432
+ readonly publicCode: CapxulErrorCode;
433
+ readonly publicError: CapxulError;
434
+ readonly cause: unknown;
435
+ readonly details?: CapxulErrorDetails;
436
+ }> {}
437
+ interface ConvexCallPort {
438
+ query<TArgs extends Record<string, unknown>, TOutput>(fn: FunctionReference<"query", "public", TArgs, TOutput>, args: TArgs): Effect.Effect<TOutput, ConvexCallError>;
439
+ mutation<TArgs extends Record<string, unknown>, TOutput>(fn: FunctionReference<"mutation", "public", TArgs, TOutput>, args: TArgs): Effect.Effect<TOutput, ConvexCallError>;
440
+ action<TArgs extends Record<string, unknown>, TOutput>(fn: FunctionReference<"action", "public", TArgs, TOutput>, args: TArgs): Effect.Effect<TOutput, ConvexCallError>;
441
+ /**
442
+ * Substrate-level reactive transport over Convex's `onUpdate`.
443
+ *
444
+ * @internal-use — substrate only; see `ports/subscription.ts`. Domain
445
+ * ports do not expose reactive callback methods to consumers (ARCH-LOCK-1).
446
+ */
447
+ subscribe<TArgs extends Record<string, unknown>, TOutput>(fn: FunctionReference<"query", "public", TArgs, TOutput>, args: TArgs, callback: (snapshot: Snapshot<TOutput>) => void): Effect.Effect<Unsubscribe, ConvexCallError>;
448
+ }
449
+ //#endregion
450
+ //#region src/ports/identity.d.ts
451
+ type CreateIdentityInput = {
452
+ readonly authUserId: AuthUserId;
453
+ readonly email: Email;
454
+ readonly displayName?: string;
455
+ readonly country?: CountryCode;
456
+ };
457
+ type UpdateIdentityInput = {
458
+ readonly authUserId: AuthUserId;
459
+ readonly displayName?: string;
460
+ readonly country?: CountryCode;
461
+ };
462
+ /**
463
+ * D-ONBOARD (#669) — the onboarding-complete identity write. Composes the
464
+ * existing create/update write into one idempotent upsert that ALSO sets the
465
+ * `onboarded` flag and persists the optional `withdrawalAddress` (the one
466
+ * allowed raw-0x class). `displayName` + `country` are required at onboarding
467
+ * time. The returned `Profile` is the existing branded shape — the onboarding
468
+ * flags live on the wire row and are not projected onto the read surface.
469
+ */
470
+ type CompleteOnboardingIdentityInput = {
471
+ readonly authUserId: AuthUserId;
472
+ readonly email: Email;
473
+ readonly displayName: string;
474
+ readonly country: CountryCode;
475
+ readonly withdrawalAddress?: Address; /** #1062: optional globally-unique handle — store-when-present, backend-normalized. */
476
+ readonly username?: string;
477
+ };
478
+ 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 & {
479
+ readonly _tag: "IdentityError";
480
+ } & Readonly<A>;
481
+ declare class IdentityError extends IdentityError_base<{
482
+ readonly operation: string;
483
+ readonly publicCode: CapxulErrorCode;
484
+ readonly publicError: CapxulError;
485
+ readonly cause: unknown;
486
+ readonly details?: CapxulErrorDetails;
487
+ }> {}
488
+ interface IdentityPort {
489
+ loadByAuthUserId(authUserId: AuthUserId): Effect.Effect<Profile | null, IdentityError, never>;
490
+ create(input: CreateIdentityInput): Effect.Effect<Profile, IdentityError, never>;
491
+ update(input: UpdateIdentityInput): Effect.Effect<Profile, IdentityError, never>;
492
+ /** D-ONBOARD (#669): idempotent upsert that marks the identity onboarded. */
493
+ completeOnboarding(input: CompleteOnboardingIdentityInput): Effect.Effect<Profile, IdentityError, never>;
494
+ }
495
+ //#endregion
496
+ //#region src/ports/smart-account.d.ts
497
+ /**
498
+ * Configuration for a Safe deployment: the chain + RPC endpoint +
499
+ * gas-sponsorship policy. `receiptTimeoutMs` is optional; the deploying
500
+ * adapter applies a default when omitted.
501
+ *
502
+ * #1145 (DEMOLITION §D4): re-homed here from the deleted
503
+ * `ports/safe-deployment.ts`. The SafeDeploymentPort itself was fakes-only
504
+ * plus one e2e adapter; the real Safe lifecycle is backend-orchestrated
505
+ * through this port. Only the two data shapes below survive on the SDK
506
+ * surface — `SafeDeploymentConfig` parameterises the org-deploy seam
507
+ * (`orgDeploymentConfig`), `SafeDeploymentEvidence` is the payload of
508
+ * `confirmDeployment`.
509
+ */
510
+ type SafeDeploymentConfig = {
511
+ readonly chainId: ChainId;
512
+ readonly rpcUrl: string;
513
+ readonly gasPolicyId: string;
514
+ readonly receiptTimeoutMs?: DurationMs;
515
+ };
516
+ /**
517
+ * Evidence of a successful Safe deployment.
518
+ *
519
+ * Every field except `chainId` / `signerAddress` / `safeAddress` is
520
+ * optional because the AC8 precheck short-circuit path (Safe already
521
+ * on-chain at this address; off-chain receipt evidence unavailable)
522
+ * calls the persistence step WITHOUT a `userOpHash`, `txHash`, or
523
+ * `blockNumber` — there is no recoverable transaction. Aaron's rule:
524
+ * "If there is no TX and it hasn't been deployed then there shouldn't
525
+ * be a hash." End-to-end nullable: `v.optional(v.string())` in the
526
+ * backend schema.
527
+ *
528
+ * **`deployedAt` is NOT a field on this type.** The SDK is never the
529
+ * oracle for `deployedAt`. The backend (`confirmDeployment` action —
530
+ * Convex mutations cannot `fetch`, so the chain re-verification lives
531
+ * in an action) derives it from on-chain data — `eth_getUserOperationReceipt`
532
+ * for the real-userOp path or `eth_getLogs` for the precheck path —
533
+ * then resolves the receipt block's timestamp via `eth_getBlockByNumber`.
534
+ * See `packages/sdk/docs/architecture.md` for the deployment trust boundary.
535
+ */
536
+ type SafeDeploymentEvidence = {
537
+ readonly chainId: ChainId;
538
+ readonly signerAddress: Address;
539
+ readonly safeAddress: Address;
540
+ readonly txHash?: TxHash;
541
+ readonly userOpHash?: TxHash;
542
+ readonly blockNumber?: BlockNumber;
543
+ };
544
+ type ProvisionInput = {
545
+ readonly authUserId: AuthUserId;
546
+ readonly chainId: ChainId;
547
+ };
548
+ /**
549
+ * Input to `SmartAccountPort.confirmDeployment` (#161 · γ-B).
550
+ *
551
+ * The SDK provides evidence pointers; the backend is the oracle for
552
+ * `deployedAt`. `evidence.deployedAt` does NOT exist by schema (see
553
+ * `SafeDeploymentEvidence`) — the backend derives `deployedAt` from
554
+ * the on-chain receipt block via `eth_getBlockByNumber`.
555
+ *
556
+ * Precheck path: `evidence.userOpHash` omitted; backend scans
557
+ * `SafeProxyFactory.ProxyCreation(safeAddress, _)` via `eth_getLogs`.
558
+ *
559
+ * Real-userOp path: `evidence.userOpHash` populated; backend calls
560
+ * `eth_getUserOperationReceipt(userOpHash)` to re-verify and derive.
561
+ */
562
+ type ConfirmDeploymentInput = {
563
+ readonly authUserId: AuthUserId;
564
+ readonly chainId: ChainId;
565
+ readonly safeAddress: Address;
566
+ readonly evidence: SafeDeploymentEvidence;
567
+ /**
568
+ * Optional live-E2E correlation id. This does not prove deployment; the
569
+ * backend still re-verifies chain evidence and only mirrors this branded
570
+ * id onto telemetry for PostHog run joins.
571
+ */
572
+ readonly telemetryRunId?: RunId;
573
+ };
574
+ /**
575
+ * Input to `SmartAccountPort.claim` (PRD #462). The authenticated session
576
+ * reports the browser-created signer address; the BACKEND builds and
577
+ * bootstrap-signs the claim userOp (deploy + swapOwner) — the consumer signs
578
+ * nothing at claim.
579
+ */
580
+ type ClaimInput = {
581
+ readonly authUserId: AuthUserId;
582
+ readonly chainId: ChainId;
583
+ readonly signerAddress: Address;
584
+ readonly telemetryRunId?: RunId;
585
+ };
586
+ 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 & {
587
+ readonly _tag: "SmartAccountError";
588
+ } & Readonly<A>;
589
+ declare class SmartAccountError extends SmartAccountError_base<{
590
+ readonly operation: string;
591
+ readonly publicCode: CapxulErrorCode;
592
+ readonly publicError: CapxulError;
593
+ readonly cause: unknown;
594
+ readonly details?: CapxulErrorDetails;
595
+ }> {}
596
+ interface SmartAccountPort {
597
+ loadByAuthUserId(authUserId: AuthUserId): Effect.Effect<SmartAccount | null, SmartAccountError, never>;
598
+ loadBySmartAccountAddress(address: Address): Effect.Effect<SmartAccount | null, SmartAccountError, never>;
599
+ provision(input: ProvisionInput): Effect.Effect<SmartAccount, SmartAccountError, never>;
600
+ /**
601
+ * Persist on-chain Safe-deployment evidence. The backend re-verifies
602
+ * the evidence against chain state and derives `deployedAt` from the
603
+ * receipt block's timestamp. Returns the updated `SmartAccount` row.
604
+ *
605
+ * γ-B trust model: the SDK supplies evidence pointers only. The
606
+ * backend is the SOLE oracle for `deployedAt` — see
607
+ * `packages/sdk/docs/architecture.md`.
608
+ */
609
+ confirmDeployment(input: ConfirmDeploymentInput): Effect.Effect<SmartAccount, SmartAccountError, never>;
610
+ /**
611
+ * Claim the account (PRD #462): the backend builds, bootstrap-signs, and
612
+ * submits ONE sponsored userOp — deploy (when undeployed) + swapOwner
613
+ * (bootstrap → `signerAddress`). Idempotent; returns the updated row. When
614
+ * another claim is in flight the row comes back with `claimedAt: null` —
615
+ * callers poll lifecycle until the claim lands.
616
+ */
617
+ claim(input: ClaimInput): Effect.Effect<SmartAccount, SmartAccountError, never>;
618
+ }
619
+ //#endregion
620
+ //#region src/ports/account-read.d.ts
621
+ type ReadAccountBalanceInput = {
622
+ readonly chainId: ChainId;
623
+ };
624
+ type FundFromFaucetInput = {
625
+ readonly chainId: ChainId;
626
+ readonly amount: Money;
627
+ };
628
+ type FundFromFaucetResult = {
629
+ readonly txHash: string;
630
+ };
631
+ 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 & {
632
+ readonly _tag: "AccountReadError";
633
+ } & Readonly<A>;
634
+ declare class AccountReadError extends AccountReadError_base<{
635
+ readonly operation: string;
636
+ readonly publicCode: CapxulErrorCode;
637
+ readonly publicError: CapxulError;
638
+ readonly cause: unknown;
639
+ readonly details?: CapxulErrorDetails;
640
+ }> {}
641
+ /**
642
+ * Logical Account money read (M2 Slice S1a). Joins the `accounts` row with a
643
+ * live RPC `balanceOf` pull; the adapter lifts wire integers to `Money`.
644
+ */
645
+ interface AccountReadPort {
646
+ readBalance(input: ReadAccountBalanceInput): Effect.Effect<Account$1, AccountReadError, never>;
647
+ fundFromFaucet(input: FundFromFaucetInput): Effect.Effect<FundFromFaucetResult, AccountReadError, never>;
648
+ }
649
+ //#endregion
650
+ //#region src/ports/sub-account.d.ts
651
+ declare const SubAccountError_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 & {
652
+ readonly _tag: "SubAccountError";
653
+ } & Readonly<A>;
654
+ declare class SubAccountError extends SubAccountError_base<{
655
+ readonly operation: string;
656
+ readonly publicCode: CapxulErrorCode;
657
+ readonly publicError: CapxulError;
658
+ readonly cause: unknown;
659
+ readonly details?: CapxulErrorDetails;
660
+ }> {}
661
+ type CreateSubAccountInput = {
662
+ readonly accountId: AccountId;
663
+ readonly name: string;
664
+ };
665
+ type SubAccountIdInput = {
666
+ readonly subAccountId: SubAccountId;
667
+ };
668
+ type RenameSubAccountInput = {
669
+ readonly subAccountId: SubAccountId;
670
+ readonly name: string;
671
+ };
672
+ /**
673
+ * A `transfer` endpoint is either the Account's MAIN balance (the remainder
674
+ * left over after every sub-account is funded — never a stored row) or a
675
+ * specific sub-account, addressed by its `SubAccountId` (canon
676
+ * `account-balance-model.md` §5, §12).
677
+ */
678
+ type TransferEndpoint = "main" | SubAccountId;
679
+ /**
680
+ * Move money between two of the SAME Account's balances (canon §12). The
681
+ * backend resolves the Account from auth (v1 = one Account per user), so the
682
+ * input carries no `accountId` — only the from/to endpoints and the `Money`
683
+ * amount. One verb covers money in (`main → sub`), money out (`sub → main`),
684
+ * and `sub → sub`.
685
+ */
686
+ type TransferInput = {
687
+ readonly from: TransferEndpoint;
688
+ readonly to: TransferEndpoint;
689
+ readonly amount: Money;
690
+ };
691
+ /**
692
+ * Result of a `transfer`: the recomputed `available` (`balanceOf − Σ`), plus
693
+ * the updated source/destination sub-account rows. An endpoint that is `"main"`
694
+ * has no stored row, so its slot is `null`.
695
+ */
696
+ type TransferResult = {
697
+ readonly available: Money;
698
+ readonly from: SubAccount | null;
699
+ readonly to: SubAccount | null;
700
+ };
701
+ interface SubAccountPort {
702
+ create(input: CreateSubAccountInput): Effect.Effect<SubAccount, SubAccountError, never>;
703
+ get(input: SubAccountIdInput): Effect.Effect<SubAccount | null, SubAccountError, never>;
704
+ list(input: {
705
+ readonly accountId: AccountId;
706
+ }): Effect.Effect<readonly SubAccount[], SubAccountError, never>;
707
+ rename(input: RenameSubAccountInput): Effect.Effect<SubAccount, SubAccountError, never>;
708
+ delete(input: SubAccountIdInput): Effect.Effect<void, SubAccountError, never>;
709
+ transfer(input: TransferInput): Effect.Effect<TransferResult, SubAccountError, never>;
710
+ }
711
+ //#endregion
712
+ //#region src/flows/types.d.ts
713
+ /**
714
+ * The full 10-port bundle that `assembleCapxulClient` (slice 5) consumes.
715
+ * (Was 13 before #1145 / DEMOLITION §D4 deleted the credentials, env and
716
+ * transport ports — built by `production.ts`, read by nobody.)
717
+ *
718
+ * The identity actor receives this bundle through `BootIdentityFlowInput` and
719
+ * uses only the existing ports needed by each work lane. Other domain flows
720
+ * retain their own narrowed inputs.
721
+ */
722
+ interface FlowPorts {
723
+ readonly authClient: AuthClientPort;
724
+ readonly authCache: AuthCachePort;
725
+ readonly identity: IdentityPort;
726
+ readonly smartAccount: SmartAccountPort;
727
+ readonly accountRead: AccountReadPort;
728
+ readonly subAccount: SubAccountPort;
729
+ readonly bootstrap: BootstrapPort;
730
+ readonly clock: ClockPort;
731
+ readonly telemetry: TelemetryPort;
732
+ readonly convexCall: ConvexCallPort;
733
+ }
734
+ /** Legacy method input retained by the imperative auth surface. */
735
+ interface ExternalSigner {
736
+ readonly address: Address;
737
+ readonly signedProof: string;
738
+ }
739
+ //#endregion
740
+ //#region ../wire/src/observation-context.d.ts
741
+ /**
742
+ * Bounded, non-authoritative observation metadata carried by selected SDK
743
+ * calls. Actor identity is deliberately absent: the backend derives it from
744
+ * the authenticated session and verifies organization/application hints.
745
+ */
746
+ interface WireObservationContext {
747
+ readonly application?: string;
748
+ readonly applicationId?: string;
749
+ readonly release?: string;
750
+ readonly sessionId?: string;
751
+ readonly organizationId?: string;
752
+ readonly journeyId?: string;
753
+ readonly correlationId?: string;
754
+ readonly anonymousId?: string;
755
+ /** W3C trace carrier for the explicit Convex action hop; never product identity. */
756
+ readonly traceparent?: string;
757
+ }
758
+ //#endregion
759
+ //#region src/surface/org-lifecycle.d.ts
760
+ type OrgSetupStep = "preparingFounderAccount" | "awaitingFounderAuthorization" | "submittingBootstrap" | "confirmingBootstrap";
761
+ /** Leak-safe readiness for exactly one Organization. */
762
+ type OrgLifecycle = {
763
+ readonly status: "loading";
764
+ readonly orgId: OrgId;
765
+ } | {
766
+ readonly status: "settingUp";
767
+ readonly orgId: OrgId;
768
+ readonly step: OrgSetupStep;
769
+ } | {
770
+ readonly status: "ready";
771
+ readonly orgId: OrgId;
772
+ readonly canTransact: true;
773
+ } | {
774
+ readonly status: "failed";
775
+ readonly orgId: OrgId;
776
+ readonly at: OrgSetupStep;
777
+ readonly error: CapxulError;
778
+ readonly retryable: boolean;
779
+ };
780
+ type StartOrResumeOrganizationInput = {
781
+ readonly name: string;
782
+ readonly handle: string;
783
+ readonly country: string; /** #1064: optional onboarding-collected description + size bucket. */
784
+ readonly bio?: string;
785
+ readonly size?: string; /** @internal Safe trace/correlation carriage owned by the identity flow. */
786
+ readonly observationContext?: WireObservationContext;
787
+ };
788
+ type OrganizationSetupStepInput = {
789
+ readonly orgId: OrgId;
790
+ readonly signal?: AbortSignal; /** @internal Safe trace/correlation carriage owned by the identity flow. */
791
+ readonly observationContext?: WireObservationContext;
792
+ };
793
+ type RecordOrganizationSetupFailureInput = {
794
+ readonly orgId: OrgId;
795
+ readonly error: CapxulError;
796
+ readonly retryable: boolean; /** @internal Safe trace/correlation carriage owned by the identity flow. */
797
+ readonly observationContext?: WireObservationContext;
798
+ };
799
+ /**
800
+ * Internal capability set used by the Core SDK's deep Organization boundary.
801
+ * Consumers never coordinate these steps directly. Production composition
802
+ * supplies them; hermetic contract tests provide a stateful implementation.
803
+ */
804
+ interface OrganizationSetupOps {
805
+ startOrResume(input: StartOrResumeOrganizationInput): Promise<CapxulResult<{
806
+ readonly orgId: OrgId;
807
+ readonly lifecycle: OrgLifecycle;
808
+ }>>;
809
+ /** Completes and verifies the founder Account ownership handoff. */
810
+ prepareFounderAccount(input: OrganizationSetupStepInput): Promise<CapxulResult<OrgLifecycle>>;
811
+ /** Obtains configured signer authorization and submits the bootstrap once. */
812
+ authorizeAndSubmitBootstrap(input: OrganizationSetupStepInput): Promise<CapxulResult<OrgLifecycle>>;
813
+ /** Resumes a recorded provider-known submission without invoking the signer. */
814
+ resumeSubmittedBootstrap(input: OrganizationSetupStepInput): Promise<CapxulResult<OrgLifecycle>>;
815
+ /** Confirms a previously recorded submission without requesting authorization again. */
816
+ confirmSubmittedBootstrap(input: OrganizationSetupStepInput): Promise<CapxulResult<OrgLifecycle>>;
817
+ recordFailure(input: RecordOrganizationSetupFailureInput): Promise<CapxulResult<OrgLifecycle>>;
818
+ loadLifecycle(input: {
819
+ readonly orgId: OrgId;
820
+ readonly observationContext?: WireObservationContext;
821
+ }): Promise<CapxulResult<OrgLifecycle>>;
822
+ /** Resets durable failure state only; the Core SDK resumes the correct step. */
823
+ retry(input: OrganizationSetupStepInput): Promise<CapxulResult<OrgLifecycle>>;
824
+ }
825
+ //#endregion
826
+ //#region src/flows/identity.d.ts
827
+ interface IdentityActor extends Actor<IdentityState, IdentityEvent, RefusalReason> {
828
+ /** Full provider session retained beside the deliberately minimal model session. */
829
+ readonly authSession: () => AuthSession | null;
830
+ /** Trust a cache-resumed provider session before a later ReadSession verifies it. */
831
+ readonly restoreAuthSession: (session: AuthSession, controls?: InvocationControls) => Effect.Effect<IdentityState, ActorFailure<RefusalReason | CapxulErrorCode>>;
832
+ }
833
+ //#endregion
834
+ //#region src/surface/auth.d.ts
835
+ type AuthMethodOptions = InvocationControls;
836
+ type SignInOptions = AuthMethodOptions;
837
+ interface AuthMethods {
838
+ canSendOtp(input: {
839
+ readonly email: string;
840
+ }, options?: AuthMethodOptions): Promise<CapxulResult<CanSendOtpStatus>>;
841
+ signIn(input: {
842
+ readonly email: string;
843
+ }, options?: SignInOptions): Promise<CapxulResult<{
844
+ readonly sessionId: string;
845
+ readonly expiresAt: number;
846
+ }>>;
847
+ verifyOtp(input: {
848
+ readonly email: string;
849
+ readonly code: string;
850
+ readonly signer?: ExternalSigner;
851
+ }, options?: AuthMethodOptions): Promise<CapxulResult<Session$1>>;
852
+ signOut(options?: AuthMethodOptions): Promise<CapxulResult<void>>;
853
+ getSession(options?: AuthMethodOptions): Promise<CapxulResult<Session$1 | null>>;
854
+ }
855
+ //#endregion
856
+ //#region src/surface/smart-account.d.ts
857
+ interface SmartAccountMethods {
858
+ loadCurrent(options?: {
859
+ readonly signal?: AbortSignal;
860
+ }): Promise<CapxulResult<SmartAccount$1 | null>>;
861
+ provision(input?: {
862
+ readonly externalSigner?: ExternalSigner;
863
+ }): Promise<CapxulResult<SmartAccount$1>>;
864
+ }
865
+ //#endregion
866
+ //#region src/surface/identity.d.ts
867
+ interface IdentityMethods {
868
+ loadCurrent(options?: {
869
+ readonly signal?: AbortSignal;
870
+ }): Promise<CapxulResult<Profile$1 | null>>;
871
+ /**
872
+ * #1062: availability probe for the username the user is typing. Returns the
873
+ * canonical stored form so the UI can echo it.
874
+ */
875
+ usernameAvailable(username: string, options?: {
876
+ readonly signal?: AbortSignal;
877
+ }): Promise<CapxulResult<{
878
+ readonly available: boolean;
879
+ readonly normalized: string;
880
+ }>>;
881
+ }
882
+ //#endregion
883
+ //#region src/surface/account-lifecycle.d.ts
884
+ type ProvisioningFailureStep = "wallet" | "identity" | "provision" | "deploy";
885
+ type ProvisioningPhase = {
886
+ readonly status: "idle";
887
+ } | {
888
+ readonly status: "wallet";
889
+ } | {
890
+ readonly status: "identity";
891
+ } | {
892
+ readonly status: "provision";
893
+ } | {
894
+ readonly status: "deploy";
895
+ } | {
896
+ readonly status: "ready";
897
+ } | {
898
+ readonly status: "failed";
899
+ readonly at: ProvisioningFailureStep;
900
+ readonly error: CapxulError;
901
+ };
902
+ type AccountSetupStep = "connecting" | "confirmingIdentity" | "registering" | "activating";
903
+ type AccountLifecycle = {
904
+ readonly status: "loading";
905
+ } | {
906
+ readonly status: "settingUp";
907
+ readonly step: AccountSetupStep;
908
+ } | {
909
+ readonly status: "ready";
910
+ readonly accountId: string;
911
+ readonly canTransact: boolean;
912
+ } | {
913
+ readonly status: "failed";
914
+ readonly at: AccountSetupStep;
915
+ readonly error: CapxulError;
916
+ };
917
+ declare function isSettingUpLifecycle(lifecycle: AccountLifecycle): boolean;
918
+ //#endregion
919
+ //#region ../wire/src/status.d.ts
920
+ /** Payment lifecycle states carried on the wire (ADR-0018 P1). */
921
+ declare const PAYMENT_STATUSES: readonly ["pending", "submitted", "pending_claim", "scheduled", "streaming", "settled", "cancelled", "redirected", "expired", "failed"];
922
+ type PaymentStatus$1 = (typeof PAYMENT_STATUSES)[number];
923
+ /** What a payment is FOR. Pairs with `PAYMENT_DOCUMENT_KINDS`. */
924
+ declare const PAYMENT_TYPES: readonly ["unspecified", "invoice", "payroll", "reimbursement"];
925
+ type PaymentType$1 = (typeof PAYMENT_TYPES)[number];
926
+ /** Attachable document kinds; each maps to exactly one `PaymentType`. */
927
+ declare const PAYMENT_DOCUMENT_KINDS: readonly ["memo", "invoice", "payslip", "receipt", "withdrawal"];
928
+ type PaymentDocumentKind$1 = (typeof PAYMENT_DOCUMENT_KINDS)[number];
929
+ /** Lifecycle of a payment REQUEST as its issuer sees it. */
930
+ declare const REQUEST_STATUSES: readonly ["draft", "sent", "viewed", "pending_settlement", "paid", "declined", "cancelled", "expired"];
931
+ type RequestStatus = (typeof REQUEST_STATUSES)[number];
932
+ /** The same request as its RECIPIENT sees it, in the approval inbox. */
933
+ declare const INBOX_STATUSES: readonly ["open", "approved", "declined", "paid", "cancelled", "expired"];
934
+ type InboxStatus = (typeof INBOX_STATUSES)[number];
935
+ //#endregion
936
+ //#region ../wire/src/financial-ops.d.ts
937
+ declare const AttachablePaymentDocumentEnvelope: Schema.Union<readonly [Schema.Struct<{
938
+ readonly protocol: Schema.Literal<"capxul.payment-document">;
939
+ readonly version: Schema.Literal<1>;
940
+ readonly domain: Schema.Struct<{
941
+ readonly name: Schema.Literal<"CapxulPayments">;
942
+ readonly version: Schema.Literal<"1">;
943
+ readonly chainId: Schema.Codec<ChainId, number, never, never>;
944
+ readonly verifyingContract: Schema.Literal<"0xe740ea65521edc9bef0ea75d30b5334711db99f4">;
945
+ }>;
946
+ readonly primaryType: Schema.Literal<"Memo">;
947
+ readonly message: Schema.Struct<{
948
+ readonly kind: Schema.Literal<0>;
949
+ readonly reference: Schema.String;
950
+ readonly note: Schema.String;
951
+ readonly issuedAt: Schema.Number;
952
+ }>;
953
+ }>, Schema.Struct<{
954
+ readonly protocol: Schema.Literal<"capxul.payment-document">;
955
+ readonly version: Schema.Literal<1>;
956
+ readonly domain: Schema.Struct<{
957
+ readonly name: Schema.Literal<"CapxulPayments">;
958
+ readonly version: Schema.Literal<"1">;
959
+ readonly chainId: Schema.Codec<ChainId, number, never, never>;
960
+ readonly verifyingContract: Schema.Literal<"0xe740ea65521edc9bef0ea75d30b5334711db99f4">;
961
+ }>;
962
+ readonly primaryType: Schema.Literal<"Invoice">;
963
+ readonly message: Schema.Struct<{
964
+ readonly kind: Schema.Literal<1>;
965
+ readonly invoiceNumber: Schema.String;
966
+ readonly payerRef: Schema.String;
967
+ readonly payeeRef: Schema.String;
968
+ readonly amount: Schema.String;
969
+ readonly currency: Schema.Codec<CurrencyCode, string, never, never>;
970
+ readonly decimals: Schema.Number;
971
+ readonly issuedAt: Schema.Number;
972
+ readonly dueAt: Schema.Number;
973
+ readonly lineItemsHash: Schema.Codec<DocumentHash, string, never, never>;
974
+ }>;
975
+ }>, Schema.Struct<{
976
+ readonly protocol: Schema.Literal<"capxul.payment-document">;
977
+ readonly version: Schema.Literal<1>;
978
+ readonly domain: Schema.Struct<{
979
+ readonly name: Schema.Literal<"CapxulPayments">;
980
+ readonly version: Schema.Literal<"1">;
981
+ readonly chainId: Schema.Codec<ChainId, number, never, never>;
982
+ readonly verifyingContract: Schema.Literal<"0xe740ea65521edc9bef0ea75d30b5334711db99f4">;
983
+ }>;
984
+ readonly primaryType: Schema.Literal<"Payslip">;
985
+ readonly message: Schema.Struct<{
986
+ readonly kind: Schema.Literal<2>;
987
+ readonly employerRef: Schema.String;
988
+ readonly employeeRef: Schema.String;
989
+ readonly period: Schema.String;
990
+ readonly gross: Schema.String;
991
+ readonly net: Schema.String;
992
+ readonly currency: Schema.Codec<CurrencyCode, string, never, never>;
993
+ readonly decimals: Schema.Number;
994
+ readonly issuedAt: Schema.Number;
995
+ }>;
996
+ }>, Schema.Struct<{
997
+ readonly protocol: Schema.Literal<"capxul.payment-document">;
998
+ readonly version: Schema.Literal<1>;
999
+ readonly domain: Schema.Struct<{
1000
+ readonly name: Schema.Literal<"CapxulPayments">;
1001
+ readonly version: Schema.Literal<"1">;
1002
+ readonly chainId: Schema.Codec<ChainId, number, never, never>;
1003
+ readonly verifyingContract: Schema.Literal<"0xe740ea65521edc9bef0ea75d30b5334711db99f4">;
1004
+ }>;
1005
+ readonly primaryType: Schema.Literal<"Receipt">;
1006
+ readonly message: Schema.Struct<{
1007
+ readonly kind: Schema.Literal<3>;
1008
+ readonly reference: Schema.String;
1009
+ readonly amount: Schema.String;
1010
+ readonly currency: Schema.Codec<CurrencyCode, string, never, never>;
1011
+ readonly decimals: Schema.Number;
1012
+ readonly paidAt: Schema.Number;
1013
+ readonly note: Schema.String;
1014
+ }>;
1015
+ }>]>;
1016
+ declare const WithdrawalDocumentEnvelope: Schema.Struct<{
1017
+ readonly protocol: Schema.Literal<"capxul.payment-document">;
1018
+ readonly version: Schema.Literal<1>;
1019
+ readonly domain: Schema.Struct<{
1020
+ readonly name: Schema.Literal<"CapxulPayments">;
1021
+ readonly version: Schema.Literal<"1">;
1022
+ readonly chainId: Schema.Codec<ChainId, number, never, never>;
1023
+ readonly verifyingContract: Schema.Literal<"0xe740ea65521edc9bef0ea75d30b5334711db99f4">;
1024
+ }>;
1025
+ readonly primaryType: Schema.Literal<"Withdrawal">;
1026
+ readonly message: Schema.Struct<{
1027
+ readonly kind: Schema.Literal<4>;
1028
+ readonly reference: Schema.String;
1029
+ readonly amount: Schema.String;
1030
+ readonly currency: Schema.Codec<CurrencyCode, string, never, never>;
1031
+ readonly decimals: Schema.Number;
1032
+ readonly destChain: Schema.Codec<ChainId, number, never, never>;
1033
+ readonly destAddress: Schema.String;
1034
+ readonly settledAt: Schema.Number;
1035
+ readonly provider: Schema.String;
1036
+ readonly note: Schema.String;
1037
+ }>;
1038
+ }>;
1039
+ declare const PaymentDocumentEnvelope: Schema.Union<readonly [Schema.Union<readonly [Schema.Struct<{
1040
+ readonly protocol: Schema.Literal<"capxul.payment-document">;
1041
+ readonly version: Schema.Literal<1>;
1042
+ readonly domain: Schema.Struct<{
1043
+ readonly name: Schema.Literal<"CapxulPayments">;
1044
+ readonly version: Schema.Literal<"1">;
1045
+ readonly chainId: Schema.Codec<ChainId, number, never, never>;
1046
+ readonly verifyingContract: Schema.Literal<"0xe740ea65521edc9bef0ea75d30b5334711db99f4">;
1047
+ }>;
1048
+ readonly primaryType: Schema.Literal<"Memo">;
1049
+ readonly message: Schema.Struct<{
1050
+ readonly kind: Schema.Literal<0>;
1051
+ readonly reference: Schema.String;
1052
+ readonly note: Schema.String;
1053
+ readonly issuedAt: Schema.Number;
1054
+ }>;
1055
+ }>, Schema.Struct<{
1056
+ readonly protocol: Schema.Literal<"capxul.payment-document">;
1057
+ readonly version: Schema.Literal<1>;
1058
+ readonly domain: Schema.Struct<{
1059
+ readonly name: Schema.Literal<"CapxulPayments">;
1060
+ readonly version: Schema.Literal<"1">;
1061
+ readonly chainId: Schema.Codec<ChainId, number, never, never>;
1062
+ readonly verifyingContract: Schema.Literal<"0xe740ea65521edc9bef0ea75d30b5334711db99f4">;
1063
+ }>;
1064
+ readonly primaryType: Schema.Literal<"Invoice">;
1065
+ readonly message: Schema.Struct<{
1066
+ readonly kind: Schema.Literal<1>;
1067
+ readonly invoiceNumber: Schema.String;
1068
+ readonly payerRef: Schema.String;
1069
+ readonly payeeRef: Schema.String;
1070
+ readonly amount: Schema.String;
1071
+ readonly currency: Schema.Codec<CurrencyCode, string, never, never>;
1072
+ readonly decimals: Schema.Number;
1073
+ readonly issuedAt: Schema.Number;
1074
+ readonly dueAt: Schema.Number;
1075
+ readonly lineItemsHash: Schema.Codec<DocumentHash, string, never, never>;
1076
+ }>;
1077
+ }>, Schema.Struct<{
1078
+ readonly protocol: Schema.Literal<"capxul.payment-document">;
1079
+ readonly version: Schema.Literal<1>;
1080
+ readonly domain: Schema.Struct<{
1081
+ readonly name: Schema.Literal<"CapxulPayments">;
1082
+ readonly version: Schema.Literal<"1">;
1083
+ readonly chainId: Schema.Codec<ChainId, number, never, never>;
1084
+ readonly verifyingContract: Schema.Literal<"0xe740ea65521edc9bef0ea75d30b5334711db99f4">;
1085
+ }>;
1086
+ readonly primaryType: Schema.Literal<"Payslip">;
1087
+ readonly message: Schema.Struct<{
1088
+ readonly kind: Schema.Literal<2>;
1089
+ readonly employerRef: Schema.String;
1090
+ readonly employeeRef: Schema.String;
1091
+ readonly period: Schema.String;
1092
+ readonly gross: Schema.String;
1093
+ readonly net: Schema.String;
1094
+ readonly currency: Schema.Codec<CurrencyCode, string, never, never>;
1095
+ readonly decimals: Schema.Number;
1096
+ readonly issuedAt: Schema.Number;
1097
+ }>;
1098
+ }>, Schema.Struct<{
1099
+ readonly protocol: Schema.Literal<"capxul.payment-document">;
1100
+ readonly version: Schema.Literal<1>;
1101
+ readonly domain: Schema.Struct<{
1102
+ readonly name: Schema.Literal<"CapxulPayments">;
1103
+ readonly version: Schema.Literal<"1">;
1104
+ readonly chainId: Schema.Codec<ChainId, number, never, never>;
1105
+ readonly verifyingContract: Schema.Literal<"0xe740ea65521edc9bef0ea75d30b5334711db99f4">;
1106
+ }>;
1107
+ readonly primaryType: Schema.Literal<"Receipt">;
1108
+ readonly message: Schema.Struct<{
1109
+ readonly kind: Schema.Literal<3>;
1110
+ readonly reference: Schema.String;
1111
+ readonly amount: Schema.String;
1112
+ readonly currency: Schema.Codec<CurrencyCode, string, never, never>;
1113
+ readonly decimals: Schema.Number;
1114
+ readonly paidAt: Schema.Number;
1115
+ readonly note: Schema.String;
1116
+ }>;
1117
+ }>]>, Schema.Struct<{
1118
+ readonly protocol: Schema.Literal<"capxul.payment-document">;
1119
+ readonly version: Schema.Literal<1>;
1120
+ readonly domain: Schema.Struct<{
1121
+ readonly name: Schema.Literal<"CapxulPayments">;
1122
+ readonly version: Schema.Literal<"1">;
1123
+ readonly chainId: Schema.Codec<ChainId, number, never, never>;
1124
+ readonly verifyingContract: Schema.Literal<"0xe740ea65521edc9bef0ea75d30b5334711db99f4">;
1125
+ }>;
1126
+ readonly primaryType: Schema.Literal<"Withdrawal">;
1127
+ readonly message: Schema.Struct<{
1128
+ readonly kind: Schema.Literal<4>;
1129
+ readonly reference: Schema.String;
1130
+ readonly amount: Schema.String;
1131
+ readonly currency: Schema.Codec<CurrencyCode, string, never, never>;
1132
+ readonly decimals: Schema.Number;
1133
+ readonly destChain: Schema.Codec<ChainId, number, never, never>;
1134
+ readonly destAddress: Schema.String;
1135
+ readonly settledAt: Schema.Number;
1136
+ readonly provider: Schema.String;
1137
+ readonly note: Schema.String;
1138
+ }>;
1139
+ }>]>;
1140
+ /**
1141
+ * #592 invoice line item. `quantity` is a positive integer; `unitMinor` is the
1142
+ * per-unit price in integer minor units. The list is canonically hashed by
1143
+ * `hashLineItems` (payment-document-hash.ts) into the Invoice `lineItemsHash`,
1144
+ * and Σ(quantity × unitMinor) MUST equal the invoice `amount`. The hash binds
1145
+ * the documentHash to the exact items; the sum-check makes the items add up to
1146
+ * the amount due. See the financial-operations contract in `packages/wire/CONTEXT.md`.
1147
+ */
1148
+ declare const LineItem: Schema.Struct<{
1149
+ readonly description: Schema.String;
1150
+ readonly quantity: Schema.Number;
1151
+ readonly unitMinor: Schema.String;
1152
+ }>;
1153
+ type AttachablePaymentDocumentEnvelopeV1 = Schema.Schema.Type<typeof AttachablePaymentDocumentEnvelope>;
1154
+ type PaymentDocumentEnvelopeV1 = Schema.Schema.Type<typeof PaymentDocumentEnvelope>;
1155
+ type WithdrawalDocumentEnvelopeV1 = Schema.Schema.Type<typeof WithdrawalDocumentEnvelope>;
1156
+ type LineItemV1 = Schema.Schema.Type<typeof LineItem>;
1157
+ //#endregion
1158
+ //#region ../wire/src/leak-safety.d.ts
1159
+ declare const OnchainEvidenceBrand: unique symbol;
1160
+ /**
1161
+ * The branded `{ userOpHash, txHash }` pair. On-chain settlement evidence is
1162
+ * INTERNAL — it flows on the server-internal channel only, never onto a wire
1163
+ * Payment or any MCP tool output. The brand makes "this is internal evidence"
1164
+ * a type, so a loose pair can't be passed where a wire field is expected.
1165
+ */
1166
+ type OnchainEvidence = {
1167
+ readonly userOpHash: string;
1168
+ readonly txHash: string;
1169
+ } & {
1170
+ readonly [OnchainEvidenceBrand]: "OnchainEvidence";
1171
+ };
1172
+ //#endregion
1173
+ //#region src/surface/money.d.ts
1174
+ type ActorReference = {
1175
+ readonly kind: "personal";
1176
+ } | {
1177
+ readonly kind: "organization";
1178
+ readonly organizationId: string;
1179
+ };
1180
+ type TargetReference = {
1181
+ readonly kind: "handle";
1182
+ readonly handle: string;
1183
+ } | {
1184
+ readonly kind: "email";
1185
+ readonly email: string;
1186
+ } | {
1187
+ readonly kind: "organization";
1188
+ readonly handle: string;
1189
+ } | {
1190
+ readonly kind: "payee";
1191
+ readonly id: string;
1192
+ } | {
1193
+ readonly kind: "destination";
1194
+ readonly id: string;
1195
+ };
1196
+ interface ResolvedTarget {
1197
+ readonly reference: TargetReference;
1198
+ readonly label: string;
1199
+ readonly kind: "person" | "organization" | "payee" | "destination";
1200
+ readonly capabilities: {
1201
+ readonly canPay: boolean;
1202
+ readonly canRequest: boolean;
1203
+ readonly canPayout: boolean;
1204
+ };
1205
+ }
1206
+ interface TargetsMethods {
1207
+ resolve(reference: TargetReference, options?: {
1208
+ readonly signal?: AbortSignal;
1209
+ }): Promise<CapxulResult<ResolvedTarget>>;
1210
+ }
1211
+ type RecipientResolutionKind = "email" | "org" | "payee";
1212
+ type Ref$1 = {
1213
+ readonly kind: "handle";
1214
+ readonly handle: string;
1215
+ } | {
1216
+ readonly kind: "email";
1217
+ readonly email: string;
1218
+ } | {
1219
+ readonly kind: "orgHandle";
1220
+ readonly orgHandle: string;
1221
+ } | {
1222
+ readonly kind: "capxulUserId";
1223
+ readonly capxulUserId: string;
1224
+ } | {
1225
+ readonly kind: "payeeId";
1226
+ readonly payeeId: string;
1227
+ };
1228
+ interface MeProfile {
1229
+ readonly authUserId: string;
1230
+ readonly email: string;
1231
+ readonly displayName: string | null;
1232
+ }
1233
+ interface DepositInstructions {
1234
+ readonly accountKind: "personalSafe" | "orgTreasury";
1235
+ readonly chainId: number;
1236
+ readonly network: "base-sepolia";
1237
+ readonly currency: "USD";
1238
+ readonly address: string;
1239
+ readonly label: string;
1240
+ }
1241
+ interface RecipientResolution {
1242
+ readonly kind: RecipientResolutionKind;
1243
+ readonly recipient: string;
1244
+ readonly label: string;
1245
+ readonly safeAddress: string;
1246
+ readonly payeeId?: string;
1247
+ readonly orgId?: string;
1248
+ readonly handle?: string;
1249
+ readonly email?: string;
1250
+ }
1251
+ interface Payee {
1252
+ readonly payeeId: string;
1253
+ readonly label: string;
1254
+ readonly recipientRef: string;
1255
+ readonly handle: string | null;
1256
+ readonly destinationKind: "email" | "org" | "payeeHandle";
1257
+ readonly safeAddress: string;
1258
+ readonly createdAt: number;
1259
+ readonly updatedAt: number;
1260
+ }
1261
+ interface MeMethods {
1262
+ get(options?: {
1263
+ readonly signal?: AbortSignal;
1264
+ }): Promise<CapxulResult<MeProfile>>;
1265
+ depositInstructions(options?: {
1266
+ readonly signal?: AbortSignal;
1267
+ }): Promise<CapxulResult<DepositInstructions>>;
1268
+ }
1269
+ interface HandlesMethods {
1270
+ resolve(handle: string, options?: {
1271
+ readonly signal?: AbortSignal;
1272
+ }): Promise<CapxulResult<RecipientResolution>>;
1273
+ }
1274
+ interface PayeesMethods {
1275
+ create(input: {
1276
+ readonly label: string;
1277
+ readonly recipient: string;
1278
+ readonly handle?: string;
1279
+ }, options?: {
1280
+ readonly signal?: AbortSignal;
1281
+ }): Promise<CapxulResult<Payee>>;
1282
+ get(payeeId: string, options?: {
1283
+ readonly signal?: AbortSignal;
1284
+ }): Promise<CapxulResult<Payee | null>>;
1285
+ resolve(recipient: string, options?: {
1286
+ readonly signal?: AbortSignal;
1287
+ }): Promise<CapxulResult<RecipientResolution>>;
1288
+ }
1289
+ interface PaymentMoney {
1290
+ readonly currency: string;
1291
+ readonly value: string;
1292
+ readonly decimals: number;
1293
+ }
1294
+ type PaymentStatus = PaymentStatus$1;
1295
+ type PaymentType = PaymentType$1;
1296
+ type PaymentDocumentKind = PaymentDocumentKind$1;
1297
+ interface PaymentDocumentRef {
1298
+ readonly documentHash: string;
1299
+ readonly kind: PaymentDocumentKind;
1300
+ readonly title?: string;
1301
+ readonly uri?: string;
1302
+ readonly issuedAt?: number;
1303
+ }
1304
+ type PaymentTiming = {
1305
+ readonly kind: "instant";
1306
+ } | {
1307
+ readonly kind: "scheduled";
1308
+ readonly at: number;
1309
+ } | {
1310
+ readonly kind: "stream";
1311
+ readonly startsAt: number;
1312
+ readonly endsAt: number;
1313
+ readonly cliffAt?: number;
1314
+ };
1315
+ interface Payment {
1316
+ readonly id: string;
1317
+ readonly status: PaymentStatus;
1318
+ readonly amount: PaymentMoney;
1319
+ readonly paymentType: PaymentType;
1320
+ readonly recipient: {
1321
+ readonly kind: "handle" | "email" | "payee" | "capxulUserId" | "me" | "org" | "external_address";
1322
+ readonly label: string;
1323
+ readonly payeeId?: string;
1324
+ };
1325
+ readonly documents: readonly PaymentDocumentRef[];
1326
+ readonly timing: PaymentTiming;
1327
+ readonly released: PaymentMoney;
1328
+ readonly availableToClaim: PaymentMoney;
1329
+ readonly createdAt: number;
1330
+ readonly updatedAt: number;
1331
+ }
1332
+ interface PaymentsPayInput {
1333
+ readonly actor?: ActorReference;
1334
+ readonly to: TargetReference;
1335
+ readonly amount: PaymentMoney;
1336
+ /**
1337
+ * How the payment is classified on the ledger. When a `document` is
1338
+ * attached, the type derived from the document kind is AUTHORITATIVE
1339
+ * (memo → unspecified, invoice → invoice, payslip → payroll, receipt →
1340
+ * reimbursement) — an explicit conflicting value is rejected with
1341
+ * INVALID_INPUT ("must match the attached document kind"). With no
1342
+ * document the explicit value is honored, defaulting to "unspecified".
1343
+ */
1344
+ readonly paymentType?: PaymentType;
1345
+ /** Full EIP-712 document envelope; hashed + stored, committed on-chain. */
1346
+ readonly document?: AttachablePaymentDocumentEnvelopeV1;
1347
+ /**
1348
+ * Timing clause (D-SHAPE · #646). Omitted ⇒ `instant` (the G2 direct-send path).
1349
+ * A `scheduled`/`stream` clause turns the payment into a Commitment
1350
+ * (escrow-vest-claim) backed by `CapxulPayments.createCommitment`.
1351
+ */
1352
+ readonly timing?: PaymentTiming;
1353
+ /**
1354
+ * #592: itemized line items backing an Invoice `document`. The backend asserts
1355
+ * `hashLineItems(lineItems) === document.lineItemsHash` AND `Σ(quantity ×
1356
+ * unitMinor) === document.amount`, then persists the list for itemized render.
1357
+ */
1358
+ readonly lineItems?: readonly LineItemV1[];
1359
+ }
1360
+ /**
1361
+ * B3 withdraw / cash-out input. Stripe-shaped: `to` is the EXTERNAL 0x wallet
1362
+ * (the ONE place the SDK accepts a raw address — the pay lane never does),
1363
+ * `amount` is a Money, `document` is the REQUIRED kind:4 Withdrawal envelope
1364
+ * (carries the audit-visible destAddress). No chain / Safe / token / hash
1365
+ * custody substrate on the input. Returns a leak-safe `Payment` whose recipient
1366
+ * label is the redacted address — never the full 0x.
1367
+ */
1368
+ interface PaymentsWithdrawInput {
1369
+ readonly to: string;
1370
+ readonly amount: PaymentMoney;
1371
+ readonly document: WithdrawalDocumentEnvelopeV1;
1372
+ }
1373
+ /**
1374
+ * Payout via a saved destination. The caller selects the destination by opaque
1375
+ * id and never re-enters a raw wallet address on this path.
1376
+ */
1377
+ interface PaymentsPayoutInput {
1378
+ readonly actor?: ActorReference;
1379
+ readonly destinationId: string;
1380
+ readonly amount: PaymentMoney;
1381
+ }
1382
+ type DestinationKind = "bank_account" | "mobile_money" | "external_account";
1383
+ type DestinationRail = {
1384
+ readonly kind: "bank";
1385
+ readonly country: string;
1386
+ readonly currency: string;
1387
+ } | {
1388
+ readonly kind: "mobile_money";
1389
+ readonly country: string;
1390
+ readonly currency: string;
1391
+ readonly provider: string;
1392
+ } | {
1393
+ readonly kind: "chain";
1394
+ readonly network: string;
1395
+ readonly asset?: string;
1396
+ };
1397
+ type DestinationPayload = {
1398
+ readonly accountHolderName: string;
1399
+ readonly bankName: string;
1400
+ readonly country: string;
1401
+ readonly currency: string;
1402
+ readonly accountNumberLast4: string;
1403
+ } | {
1404
+ readonly provider: string;
1405
+ readonly country: string;
1406
+ readonly currency: string;
1407
+ readonly phoneNumberLast4: string;
1408
+ } | {
1409
+ readonly network: "base-sepolia" | "solana-devnet" | "starknet-sepolia";
1410
+ readonly address: string;
1411
+ };
1412
+ interface Destination {
1413
+ readonly id: string;
1414
+ readonly counterpartyId: string;
1415
+ /** #1063: null exactly when `ownerScope === "self"`. */
1416
+ readonly ref: Ref$1 | null;
1417
+ /** Derived from `ref`; null for self-owned rows. */
1418
+ readonly target: TargetReference | null;
1419
+ readonly kind: DestinationKind;
1420
+ readonly rail: DestinationRail;
1421
+ /**
1422
+ * #1063: "self" = the actor's own payout destination; "counterparty" = the
1423
+ * address-book shape. The mapping always sets it (wire absence ⇒ "counterparty").
1424
+ */
1425
+ readonly ownerScope: "self" | "counterparty";
1426
+ readonly label: string | null;
1427
+ readonly payload: DestinationPayload;
1428
+ readonly createdAt: number;
1429
+ readonly updatedAt: number;
1430
+ }
1431
+ /** #1063 ratified shape: your own payout destination is `target: { self: true }`. */
1432
+ type SelfTarget = {
1433
+ readonly self: true;
1434
+ };
1435
+ /** #1063: exactly one of `target` (counterparty or `{ self: true }`) or `ref`. */
1436
+ interface DestinationAddInput {
1437
+ readonly actor?: ActorReference;
1438
+ readonly target?: TargetReference | SelfTarget;
1439
+ readonly ref?: Ref$1;
1440
+ readonly kind: DestinationKind;
1441
+ readonly label?: string;
1442
+ readonly payload: DestinationPayload;
1443
+ }
1444
+ interface DestinationListInput {
1445
+ readonly actor?: ActorReference;
1446
+ /** #1063: `{ self: true }` narrows to the actor's own payout destinations. */
1447
+ readonly target?: TargetReference | SelfTarget;
1448
+ readonly ref?: Ref$1;
1449
+ readonly kind?: DestinationKind;
1450
+ }
1451
+ interface DestinationRemoveInput {
1452
+ readonly actor?: ActorReference;
1453
+ readonly destinationId: string;
1454
+ }
1455
+ interface DestinationsMethods {
1456
+ add(input: DestinationAddInput, options?: {
1457
+ readonly signal?: AbortSignal;
1458
+ }): Promise<CapxulResult<Destination>>;
1459
+ list(input: DestinationListInput, options?: {
1460
+ readonly signal?: AbortSignal;
1461
+ }): Promise<CapxulResult<readonly Destination[]>>;
1462
+ remove(input: DestinationRemoveInput, options?: {
1463
+ readonly signal?: AbortSignal;
1464
+ }): Promise<CapxulResult<{
1465
+ readonly id: string;
1466
+ }>>;
1467
+ }
1468
+ interface ActivityListParams {
1469
+ readonly actor?: ActorReference;
1470
+ readonly cursor?: string;
1471
+ readonly limit?: number;
1472
+ readonly paymentType?: PaymentType;
1473
+ readonly timing?: PaymentTiming["kind"];
1474
+ }
1475
+ interface ActivityItem {
1476
+ readonly id: string;
1477
+ readonly actor: ActorReference;
1478
+ readonly kind: "payment" | "payout" | "withdrawal" | "deposit" | "claim";
1479
+ readonly direction: "in" | "out" | "internal";
1480
+ readonly status: PaymentStatus;
1481
+ readonly amount: PaymentMoney;
1482
+ readonly title: string;
1483
+ readonly subtitle: string | null;
1484
+ readonly target: TargetReference | null;
1485
+ readonly paymentId: string | null;
1486
+ readonly createdAt: number;
1487
+ readonly updatedAt: number;
1488
+ }
1489
+ interface ActivityPage {
1490
+ readonly items: readonly ActivityItem[];
1491
+ readonly nextCursor: string | null;
1492
+ }
1493
+ interface ActivityMethods {
1494
+ list(params?: ActivityListParams, options?: {
1495
+ readonly signal?: AbortSignal;
1496
+ }): Promise<CapxulResult<ActivityPage>>;
1497
+ }
1498
+ interface OfframpQuoteInput {
1499
+ readonly actor?: ActorReference;
1500
+ readonly destinationId: string;
1501
+ readonly amount: PaymentMoney;
1502
+ }
1503
+ interface OfframpQuote {
1504
+ readonly id: string;
1505
+ readonly input: OfframpQuoteInput;
1506
+ readonly expiresAt: number;
1507
+ readonly receivedAmount: PaymentMoney;
1508
+ readonly fee: PaymentMoney;
1509
+ }
1510
+ interface OfframpStatus {
1511
+ readonly id: string;
1512
+ readonly status: "pending" | "processing" | "completed" | "failed" | "cancelled";
1513
+ readonly paymentId: string | null;
1514
+ readonly destinationId: string;
1515
+ readonly updatedAt: number;
1516
+ }
1517
+ interface OfframpMethods {
1518
+ quote(input: OfframpQuoteInput, options?: {
1519
+ readonly signal?: AbortSignal;
1520
+ }): Promise<CapxulResult<OfframpQuote>>;
1521
+ status(offrampId: string, options?: {
1522
+ readonly signal?: AbortSignal;
1523
+ }): Promise<CapxulResult<OfframpStatus>>;
1524
+ }
1525
+ interface PaymentSettlementInput {
1526
+ readonly paymentId: string;
1527
+ readonly evidence: OnchainEvidence;
1528
+ }
1529
+ /**
1530
+ * Host-execution callback recording the on-chain escrow of a commitment
1531
+ * (G3 · #546): `createCommitment` returned `onchainCommitmentId`, escrowing
1532
+ * the total. `onchainCommitmentId` + the userOp/tx hashes are internal evidence,
1533
+ * never on the wire (internal channel only).
1534
+ */
1535
+ interface CommitmentCreatedInput {
1536
+ readonly paymentId: string;
1537
+ readonly onchainCommitmentId: string;
1538
+ readonly evidence: OnchainEvidence;
1539
+ }
1540
+ /** Host-execution callback recording a recipient-side `claim` (G3 · #546). */
1541
+ interface CommitmentClaimInput {
1542
+ readonly paymentId: string;
1543
+ readonly evidence: OnchainEvidence;
1544
+ }
1545
+ /**
1546
+ * Host-execution callback recording a creator-side `cancel` (G3 · #546):
1547
+ * on-chain the unvested remainder returns to the creator; vested-unclaimed
1548
+ * stays the recipient's. An optional credit-note document is appended.
1549
+ */
1550
+ interface CommitmentCancelInput {
1551
+ readonly paymentId: string;
1552
+ readonly evidence: OnchainEvidence;
1553
+ readonly document?: PaymentDocumentEnvelopeV1;
1554
+ }
1555
+ /**
1556
+ * Host-execution callback recording a pre-claim `redirect` to a new validated
1557
+ * recipient (G3 · #546). `to` is a validated recipient (handle/email/payee id),
1558
+ * never a raw address.
1559
+ */
1560
+ interface CommitmentRedirectInput {
1561
+ readonly paymentId: string;
1562
+ readonly to: Ref$1;
1563
+ readonly evidence: OnchainEvidence;
1564
+ readonly document?: PaymentDocumentEnvelopeV1;
1565
+ }
1566
+ /**
1567
+ * Host-execution callback recording a settled ORG spend/payroll on the ONE
1568
+ * `payments` ledger (D3 · #565). An org spend is a KIND of Payment — it lands a
1569
+ * real `payments` row with `source:"org"` + `orgId` (no parallel `orgSpends`
1570
+ * table, no synthetic client-side fabrication). The signer-side host calls this
1571
+ * AFTER the on-chain Roles-modifier spend settles; `evidence` carries the
1572
+ * internal userOp/tx hashes (never wire fields). `recipient` is the validated
1573
+ * recipient ref label; `recipientSafeAddress` is internal evidence on the row.
1574
+ */
1575
+ interface OrgPaymentRecordInput {
1576
+ readonly orgId: string;
1577
+ readonly recipientLabel: string;
1578
+ readonly recipientKind?: "handle" | "email" | "payee" | "capxulUserId" | "me" | "org";
1579
+ readonly recipientRef?: string;
1580
+ readonly recipientPayeeId?: string;
1581
+ readonly recipientSafeAddress: string;
1582
+ readonly amount: PaymentMoney;
1583
+ readonly paymentType: PaymentType;
1584
+ readonly document?: PaymentDocumentEnvelopeV1;
1585
+ /** The org Safe the spend debited — bound as the `from` of the settlement transfer. */
1586
+ readonly orgSafeAddress: string;
1587
+ /**
1588
+ * 0-based occurrence among batch runs with the same (recipient, amount), so
1589
+ * each run binds to + de-dupes on its own on-chain `Transfer` (D3 · #565).
1590
+ */
1591
+ readonly occurrenceIndex: number;
1592
+ readonly evidence: OnchainEvidence;
1593
+ }
1594
+ interface PaymentDocumentVerification {
1595
+ readonly documentHash: string;
1596
+ readonly ok: boolean;
1597
+ readonly derivedHash: string;
1598
+ readonly kind: PaymentDocumentKind;
1599
+ }
1600
+ /**
1601
+ * #577 render-on-demand result. `html` is self-contained user-visible document
1602
+ * HTML (stylesheet + rendered document). The MCP `paymentDocuments.render` tool
1603
+ * exposes only `{documentHash, kind, ok}` to the model and returns `html` in an
1604
+ * audience:["user"] content block (#506 redaction matrix).
1605
+ */
1606
+ interface PaymentDocumentRender {
1607
+ readonly documentHash: string;
1608
+ readonly ok: boolean;
1609
+ readonly kind: PaymentDocumentKind;
1610
+ readonly html: string;
1611
+ }
1612
+ /**
1613
+ * Internal commitment execution reference (G3 · #546). The on-chain
1614
+ * `onchainCommitmentId` is internal evidence (like userOp/tx hashes) — it never
1615
+ * appears on the wire `Payment` or any MCP tool output, but the signer-side host
1616
+ * needs it to build a claim/cancel/redirect UserOp. This is the server-internal
1617
+ * channel that carries it (and the recipient Safe address for an auto-claim
1618
+ * relayer), never a consumer-facing surface.
1619
+ */
1620
+ interface PaymentCommitmentRef {
1621
+ readonly paymentId: string;
1622
+ readonly onchainCommitmentId: string | null;
1623
+ readonly status: PaymentStatus;
1624
+ }
1625
+ /**
1626
+ * The host-execution + on-chain-evidence channel for Payments (D2 · #564).
1627
+ * SPLIT OFF the public `PaymentsMethods` so an external builder consuming
1628
+ * `@capxul/sdk` directly never sees the custody substrate. Reached only via
1629
+ * `client.payments._internal` (mirrors `client._internal.*`); the signer-side
1630
+ * host (the dev MCP edge / a self-custody integrator) drives it AFTER executing
1631
+ * a UserOp. Every input carries the `OnchainEvidence` brand — never a wire field.
1632
+ */
1633
+ interface PaymentsInternalMethods {
1634
+ /** Report on-chain settlement evidence for an instant payment. */
1635
+ markSettled(input: PaymentSettlementInput, options?: {
1636
+ readonly signal?: AbortSignal;
1637
+ }): Promise<CapxulResult<Payment>>;
1638
+ /**
1639
+ * B3: report on-chain settlement evidence for a withdraw/cash-out. The
1640
+ * backend binds the userOp to a matching external `Transfer` before settling.
1641
+ */
1642
+ markWithdrawalSettled(input: PaymentSettlementInput, options?: {
1643
+ readonly signal?: AbortSignal;
1644
+ }): Promise<CapxulResult<Payment>>;
1645
+ /**
1646
+ * Record the on-chain escrow of a commitment after `createCommitment` returns
1647
+ * its `onchainCommitmentId` (G3 · #546).
1648
+ */
1649
+ markCommitmentCreated(input: CommitmentCreatedInput, options?: {
1650
+ readonly signal?: AbortSignal;
1651
+ }): Promise<CapxulResult<Payment>>;
1652
+ /**
1653
+ * Record a settled ORG spend/payroll on the one `payments` ledger
1654
+ * (D3 · #565) — `source:"org"` + `orgId`, read back as a leak-safe Payment.
1655
+ */
1656
+ recordOrgPayment(input: OrgPaymentRecordInput, options?: {
1657
+ readonly signal?: AbortSignal;
1658
+ }): Promise<CapxulResult<Payment>>;
1659
+ /** Record a recipient-side `claim` after the on-chain claim UserOp settles. */
1660
+ claim(input: CommitmentClaimInput, options?: {
1661
+ readonly signal?: AbortSignal;
1662
+ }): Promise<CapxulResult<Payment>>;
1663
+ /** Record a creator-side `cancel` reclaiming only the unvested remainder. */
1664
+ cancel(input: CommitmentCancelInput, options?: {
1665
+ readonly signal?: AbortSignal;
1666
+ }): Promise<CapxulResult<Payment>>;
1667
+ /** Record a pre-claim `redirect` to a new validated recipient. */
1668
+ redirect(input: CommitmentRedirectInput, options?: {
1669
+ readonly signal?: AbortSignal;
1670
+ }): Promise<CapxulResult<Payment>>;
1671
+ /**
1672
+ * The on-chain commitment reference the signer-side host needs to build a
1673
+ * claim/cancel/redirect UserOp. `onchainCommitmentId` is internal evidence.
1674
+ */
1675
+ commitmentRef(paymentId: string, options?: {
1676
+ readonly signal?: AbortSignal;
1677
+ }): Promise<CapxulResult<PaymentCommitmentRef | null>>;
1678
+ }
1679
+ /**
1680
+ * The PUBLIC, Stripe-shaped Payments surface (D2 · #564). Genus verbs only —
1681
+ * `pay` / `list` / `get`. No `userOpHash` / `txHash` / `onchainCommitmentId` /
1682
+ * `chainId` / `safeAddress`. Host-execution + on-chain evidence live on the
1683
+ * `_internal` channel below; an external builder never touches custody substrate.
1684
+ */
1685
+ interface PaymentsMethods {
1686
+ pay(input: PaymentsPayInput, options?: {
1687
+ readonly signal?: AbortSignal;
1688
+ }): Promise<CapxulResult<Payment>>;
1689
+ payout(input: PaymentsPayoutInput, options?: {
1690
+ readonly signal?: AbortSignal;
1691
+ }): Promise<CapxulResult<Payment>>;
1692
+ /**
1693
+ * B3 withdraw / cash-out: send USDX from the user's custody Safe to an
1694
+ * external 0x wallet, minting a kind:4 Withdrawal document. Returns a
1695
+ * leak-safe `Payment` (recipient label is the redacted address).
1696
+ */
1697
+ withdraw(input: PaymentsWithdrawInput, options?: {
1698
+ readonly signal?: AbortSignal;
1699
+ }): Promise<CapxulResult<Payment>>;
1700
+ list(options?: {
1701
+ readonly signal?: AbortSignal;
1702
+ }): Promise<CapxulResult<readonly Payment[]>>;
1703
+ get(paymentId: string, options?: {
1704
+ readonly signal?: AbortSignal;
1705
+ }): Promise<CapxulResult<Payment | null>>;
1706
+ cancel(paymentId: string, options?: {
1707
+ readonly signal?: AbortSignal;
1708
+ }): Promise<CapxulResult<Payment>>;
1709
+ /**
1710
+ * Host-execution + on-chain-evidence channel — off the public surface
1711
+ * (production-surface-policy.md pattern). Self-custody integrators drive this;
1712
+ * a Stripe-shaped consumer never does.
1713
+ *
1714
+ * @internal-use
1715
+ */
1716
+ readonly _internal: PaymentsInternalMethods;
1717
+ }
1718
+ interface PaymentDocumentsMethods {
1719
+ verify(documentHash: string, options?: {
1720
+ readonly signal?: AbortSignal;
1721
+ }): Promise<CapxulResult<PaymentDocumentVerification>>;
1722
+ /**
1723
+ * #577: render-on-demand. Loads the owner's stored document by `documentHash`,
1724
+ * re-verifies its EIP-712 hash, and renders it to self-contained HTML using the
1725
+ * verified stored line items. Returns `{documentHash, kind, ok, html}`.
1726
+ */
1727
+ render(documentHash: string, options?: {
1728
+ readonly signal?: AbortSignal;
1729
+ }): Promise<CapxulResult<PaymentDocumentRender>>;
1730
+ }
1731
+ interface ReconciliationEntry {
1732
+ readonly paymentRequestId: string;
1733
+ readonly reference: string;
1734
+ readonly status: "paid" | "exception";
1735
+ readonly settledPaymentId: string | null;
1736
+ readonly receiptDocumentHash: string | null;
1737
+ }
1738
+ interface FinancialOpsMethods {
1739
+ readonly me: MeMethods;
1740
+ readonly handles: HandlesMethods;
1741
+ readonly payees: PayeesMethods;
1742
+ readonly targets: TargetsMethods;
1743
+ readonly destinations: DestinationsMethods;
1744
+ readonly payments: PaymentsMethods;
1745
+ readonly activity: ActivityMethods;
1746
+ readonly offramp: OfframpMethods;
1747
+ readonly paymentDocuments: PaymentDocumentsMethods;
1748
+ }
1749
+ //#endregion
1750
+ //#region src/surface/contacts.d.ts
1751
+ type ActorScopeRef = {
1752
+ readonly kind: "account";
1753
+ } | {
1754
+ readonly kind: "org";
1755
+ readonly orgId: string;
1756
+ };
1757
+ interface ActorProfile {
1758
+ readonly actor: ActorScopeRef;
1759
+ readonly displayName: string | null;
1760
+ readonly email?: string;
1761
+ readonly handle?: string;
1762
+ }
1763
+ interface AddressBookEntry {
1764
+ readonly id: string;
1765
+ readonly ref: Ref$1;
1766
+ readonly label: string;
1767
+ readonly relationship: readonly ("paid" | "paidBy" | "requested" | "member" | "employee")[];
1768
+ readonly hidden: boolean;
1769
+ }
1770
+ interface AddressBookAddInput {
1771
+ readonly ref: Ref$1;
1772
+ readonly label?: string;
1773
+ }
1774
+ interface AddressBookLabelInput {
1775
+ readonly entryId: string;
1776
+ readonly label: string;
1777
+ }
1778
+ interface AddressBookMethods {
1779
+ list(options?: {
1780
+ readonly signal?: AbortSignal;
1781
+ }): Promise<CapxulResult<readonly AddressBookEntry[]>>;
1782
+ get(entryId: string, options?: {
1783
+ readonly signal?: AbortSignal;
1784
+ }): Promise<CapxulResult<AddressBookEntry | null>>;
1785
+ add(input: AddressBookAddInput, options?: {
1786
+ readonly signal?: AbortSignal;
1787
+ }): Promise<CapxulResult<AddressBookEntry>>;
1788
+ hide(entryId: string, options?: {
1789
+ readonly signal?: AbortSignal;
1790
+ }): Promise<CapxulResult<AddressBookEntry>>;
1791
+ unhide(entryId: string, options?: {
1792
+ readonly signal?: AbortSignal;
1793
+ }): Promise<CapxulResult<AddressBookEntry>>;
1794
+ label(input: AddressBookLabelInput, options?: {
1795
+ readonly signal?: AbortSignal;
1796
+ }): Promise<CapxulResult<AddressBookEntry>>;
1797
+ }
1798
+ interface ActorRequest {
1799
+ readonly id: string;
1800
+ readonly payer?: Ref$1;
1801
+ readonly amount: PaymentMoney;
1802
+ readonly reference: string;
1803
+ readonly status: RequestStatus;
1804
+ readonly expiresAt: number | null;
1805
+ }
1806
+ interface ActorRequestIssueInput {
1807
+ readonly payer: Ref$1;
1808
+ readonly amount: PaymentMoney;
1809
+ readonly reference: string;
1810
+ readonly memo?: string;
1811
+ readonly expiresAt?: number;
1812
+ }
1813
+ interface ActorRequestsMethods {
1814
+ issue(input: ActorRequestIssueInput, options?: {
1815
+ readonly signal?: AbortSignal;
1816
+ }): Promise<CapxulResult<ActorRequest>>;
1817
+ list(options?: {
1818
+ readonly signal?: AbortSignal;
1819
+ }): Promise<CapxulResult<readonly ActorRequest[]>>;
1820
+ get(requestId: string, options?: {
1821
+ readonly signal?: AbortSignal;
1822
+ }): Promise<CapxulResult<ActorRequest | null>>;
1823
+ cancel(requestId: string, options?: {
1824
+ readonly signal?: AbortSignal;
1825
+ }): Promise<CapxulResult<ActorRequest>>;
1826
+ reconcile(options?: {
1827
+ readonly signal?: AbortSignal;
1828
+ }): Promise<CapxulResult<readonly ReconciliationEntry[]>>;
1829
+ }
1830
+ interface InboxItem {
1831
+ readonly id: string;
1832
+ readonly issuer: Ref$1;
1833
+ readonly amount: PaymentMoney;
1834
+ readonly reference: string;
1835
+ readonly status: InboxStatus;
1836
+ }
1837
+ interface InboxApproveInput {
1838
+ readonly requestId: string;
1839
+ readonly timing?: PaymentTiming;
1840
+ }
1841
+ interface InboxMethods {
1842
+ list(options?: {
1843
+ readonly signal?: AbortSignal;
1844
+ }): Promise<CapxulResult<readonly InboxItem[]>>;
1845
+ approve(input: InboxApproveInput, options?: {
1846
+ readonly signal?: AbortSignal;
1847
+ }): Promise<CapxulResult<Payment>>;
1848
+ decline(requestId: string, options?: {
1849
+ readonly signal?: AbortSignal;
1850
+ }): Promise<CapxulResult<InboxItem>>;
1851
+ }
1852
+ interface InsightsSummary {
1853
+ readonly pending: {
1854
+ readonly count: number;
1855
+ readonly total: PaymentMoney;
1856
+ };
1857
+ readonly paidThisMonth: {
1858
+ readonly count: number;
1859
+ readonly total: PaymentMoney;
1860
+ };
1861
+ readonly drafts: {
1862
+ readonly count: number;
1863
+ };
1864
+ readonly reconciliation: {
1865
+ readonly open: number;
1866
+ readonly exceptions: number;
1867
+ };
1868
+ }
1869
+ interface InsightsMethods {
1870
+ summary(options?: {
1871
+ readonly signal?: AbortSignal;
1872
+ }): Promise<CapxulResult<InsightsSummary>>;
1873
+ history(options?: {
1874
+ readonly signal?: AbortSignal;
1875
+ }): Promise<CapxulResult<readonly Payment[]>>;
1876
+ }
1877
+ interface ActorProfileMethods {
1878
+ get(options?: {
1879
+ readonly signal?: AbortSignal;
1880
+ }): Promise<CapxulResult<ActorProfile>>;
1881
+ depositInstructions(options?: {
1882
+ readonly signal?: AbortSignal;
1883
+ }): Promise<CapxulResult<DepositInstructions>>;
1884
+ }
1885
+ interface ActorRelationshipMethods {
1886
+ readonly addressBook: AddressBookMethods;
1887
+ readonly requests: ActorRequestsMethods;
1888
+ readonly inbox: InboxMethods;
1889
+ readonly insights: InsightsMethods;
1890
+ readonly profile: ActorProfileMethods;
1891
+ }
1892
+ //#endregion
1893
+ //#region src/surface/account.d.ts
1894
+ type AccountStatus = {
1895
+ readonly status: "notAuthenticated";
1896
+ } | {
1897
+ readonly status: "accountRequired";
1898
+ readonly requirement: AccountRequirement;
1899
+ readonly chainId: number;
1900
+ } | {
1901
+ readonly status: "accountProviderReady";
1902
+ readonly requirement: AccountRequirement;
1903
+ readonly chainId: number;
1904
+ readonly source: AccountProviderSource;
1905
+ readonly signerAddress: Address;
1906
+ } | {
1907
+ readonly status: "accountPrepared";
1908
+ readonly requirement: AccountRequirement;
1909
+ readonly account: SmartAccount;
1910
+ readonly deployment: {
1911
+ readonly status: "counterfactual";
1912
+ };
1913
+ } | {
1914
+ readonly status: "accountReady";
1915
+ readonly requirement: AccountRequirement;
1916
+ readonly account: SmartAccount | null;
1917
+ readonly deployment: {
1918
+ readonly status: "counterfactual";
1919
+ } | {
1920
+ readonly status: "deployed";
1921
+ readonly deployedAt: SmartAccount["deployedAt"];
1922
+ };
1923
+ };
1924
+ /**
1925
+ * Public consumer-facing surface (issue #159 · AC1+AC3). Exactly two
1926
+ * methods. `provision` and `deploySafe` are intentionally NOT here —
1927
+ * they are advanced/testing-only and will live on
1928
+ * `client._internal.account` when sibling issue #161 lands. Per
1929
+ * `packages/sdk/CONTEXT.md`, the narrowing is enforced at
1930
+ * both the type level (the `keyof AccountMethods` extract is exactly
1931
+ * `"getStatus" | "ensureReady"`) and at runtime (the bundle returned
1932
+ * here has those two own-keys and nothing else).
1933
+ *
1934
+ * Per `packages/sdk/docs/architecture.md`, the
1935
+ * `AccountStatus` discriminant — including the variants this slice can
1936
+ * only reach via `getStatus` (e.g. `accountPrepared`) — is the durable
1937
+ * shape consumers depend on. Sibling #161 will extend `ensureReady` to
1938
+ * advance the ladder past `accountProviderReady` and from
1939
+ * `accountPrepared` to `accountReady(deployed)`; until then, the type
1940
+ * surface is stable and the runtime fixed-point is documented.
1941
+ */
1942
+ interface AccountMethods extends ActorRelationshipMethods {
1943
+ /**
1944
+ * Post-auth account setup lifecycle — domain vocabulary over the internal
1945
+ * readiness ladder + provisioning lane (#356).
1946
+ */
1947
+ getLifecycle(): Promise<CapxulResult<AccountLifecycle>>;
1948
+ /** Resume setup after `failed` and return the updated lifecycle snapshot. */
1949
+ retrySetup(): Promise<CapxulResult<AccountLifecycle>>;
1950
+ /**
1951
+ * Internal advanced surface (#161 · AC1). Reserved for the rebuild's
1952
+ * own `ensureReady` upward transitions and for testing harnesses;
1953
+ * consumers MUST NOT depend on this in production. Tagged
1954
+ * `@internal-use` per `.claude/rules/flow-internal-substrate.md`.
1955
+ *
1956
+ * @internal-use
1957
+ */
1958
+ readonly _internal: AccountInternalSurface;
1959
+ }
1960
+ /**
1961
+ * Internal `provision` + `deploySafe` arms exposed at
1962
+ * `client._internal.account` (#161). Each returns `Promise<CapxulResult<T>>`
1963
+ * with the same error catalog the public methods use.
1964
+ *
1965
+ * @internal-use
1966
+ */
1967
+ interface AccountInternalSurface {
1968
+ provision(): Promise<CapxulResult<SmartAccount>>;
1969
+ deploySafe(observationSource?: unknown): Promise<CapxulResult<SmartAccount>>;
1970
+ /** @internal-use Substrate readiness ladder — tests and e2e only. */
1971
+ getStatus(): Promise<CapxulResult<AccountStatus>>;
1972
+ /** @internal-use Lane runner — tests and e2e only. */
1973
+ ensureReady(): Promise<CapxulResult<AccountStatus>>;
1974
+ /** @internal-use Provisioning lane phase — tests and e2e only. */
1975
+ getProvisioningPhase(): Promise<CapxulResult<ProvisioningPhase>>;
1976
+ /** @internal-use Lane retry — tests and e2e only. */
1977
+ retryProvisioning(): Promise<CapxulResult<ProvisioningPhase>>;
1978
+ }
1979
+ //#endregion
1980
+ //#region src/surface/accounts.d.ts
1981
+ interface AccountsMethods {
1982
+ read(options?: {
1983
+ readonly signal?: AbortSignal;
1984
+ }): Promise<CapxulResult<Account$1>>;
1985
+ }
1986
+ /**
1987
+ * Faucet surface (dev-only). Deliberately OFF the public `AccountsMethods`;
1988
+ * reachable only via `client._internal.accounts` (production-surface-policy.md).
1989
+ * The reference CLI uses it behind a test-env gate — consumers never see `fund`.
1990
+ */
1991
+ interface AccountsFaucetMethods {
1992
+ fund(amount: Money, options?: {
1993
+ readonly signal?: AbortSignal;
1994
+ }): Promise<CapxulResult<{
1995
+ readonly txHash: string;
1996
+ }>>;
1997
+ }
1998
+ //#endregion
1999
+ //#region src/domain/org/spend-gate.d.ts
2000
+ /**
2001
+ * The role's allowed recipients. The address form backs the S4 `spend` path
2002
+ * (recipient is a resolved `Address`); the string form backs the G4
2003
+ * `spendViaPayments` / `batchPayroll` path, whose recipient is a VALIDATED REF
2004
+ * (handle/email/payee/org) compared in the same ref space as the role's set.
2005
+ * Comparison is case-insensitive over the raw string value either way.
2006
+ */
2007
+ type SpendGateRecipients = "anyone" | readonly (Address | string)[];
2008
+ type SpendGateSubAccountScope = {
2009
+ readonly scope: "all";
2010
+ } | {
2011
+ readonly scope: "only";
2012
+ readonly subAccountIds: readonly SubAccountId[];
2013
+ };
2014
+ //#endregion
2015
+ //#region src/ports/org.d.ts
2016
+ /**
2017
+ * The minimal `{from, to, amount}` spend shape the authority read keys off
2018
+ * (D3 #565). The legacy address-keyed `OrgSpendInput`/`org.spend` lane was
2019
+ * hard-removed when `orgSpends` folded into the one `payments` ledger; the
2020
+ * leak-safe ref-based lane (`spendViaPayments`/`batchPayroll`) constructs this
2021
+ * internally and enforces the real validated recipient on the gate.
2022
+ */
2023
+ type OrgSpendShape = {
2024
+ readonly from: SubAccountId;
2025
+ readonly to: Address;
2026
+ readonly amount: Money;
2027
+ };
2028
+ type CreateOrgPortInput = {
2029
+ readonly input: CreateOrgInput;
2030
+ };
2031
+ type ReadOrgTreasuryInput = {
2032
+ readonly orgId: OrgId;
2033
+ };
2034
+ type ListOrgsInput = Record<never, never>;
2035
+ type ListOrgRolesInput = {
2036
+ readonly orgId: OrgId;
2037
+ };
2038
+ type ListOrgMembersInput = {
2039
+ readonly orgId: OrgId;
2040
+ };
2041
+ type InviteOrgMemberInput = {
2042
+ readonly orgId: OrgId;
2043
+ readonly input: InviteMemberInput;
2044
+ };
2045
+ type ResendOrgInviteTokenInput = {
2046
+ readonly orgId: OrgId;
2047
+ readonly email: string;
2048
+ };
2049
+ type DetectPendingOrgInvitationsInput = Record<never, never>;
2050
+ type DetectPendingOrgInvitationsResult$1 = {
2051
+ readonly matched: readonly OrgId[];
2052
+ };
2053
+ type DeployOrgRolesInput = {
2054
+ readonly orgId: OrgId;
2055
+ };
2056
+ type OrgRolesDeploymentResult = {
2057
+ readonly orgId: OrgId;
2058
+ readonly roles: readonly RoleView[];
2059
+ };
2060
+ type GrantOrgRoleInput = {
2061
+ readonly orgId: OrgId;
2062
+ readonly input: AssignRoleInput;
2063
+ };
2064
+ type RevokeOrgRoleInput = {
2065
+ readonly orgId: OrgId;
2066
+ readonly input: RemoveMemberInput;
2067
+ };
2068
+ type OrgSpendAuthority = {
2069
+ readonly activeMember: boolean;
2070
+ readonly subAccountBalanceRaw: string;
2071
+ readonly recipients: SpendGateRecipients;
2072
+ readonly subAccounts: SpendGateSubAccountScope;
2073
+ readonly perTxCapRaw?: string | null;
2074
+ readonly perDayCapRaw?: string | null;
2075
+ readonly spentTodayRaw?: string | null;
2076
+ readonly role?: string;
2077
+ };
2078
+ type ReadOrgSpendAuthorityInput = {
2079
+ readonly orgId: OrgId;
2080
+ readonly input: OrgSpendShape;
2081
+ readonly amountRaw: string;
2082
+ };
2083
+ 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 & {
2084
+ readonly _tag: "OrgError";
2085
+ } & Readonly<A>;
2086
+ declare class OrgError extends OrgError_base<{
2087
+ readonly operation: string;
2088
+ readonly publicCode: CapxulErrorCode;
2089
+ readonly publicError: CapxulError;
2090
+ readonly cause: unknown;
2091
+ readonly details?: CapxulErrorDetails;
2092
+ }> {}
2093
+ /**
2094
+ * Live org seam. `createOrg` runs the SDK-orchestrated deploy (D10) and returns
2095
+ * the created `OrgView` (its treasury is the real M2 `Account` over the Org
2096
+ * Safe — $0 at creation, D3). `readTreasury` pulls the org's Account via RPC
2097
+ * `balanceOf` (D3). `listOrgs` lists the orgs the authenticated user belongs to.
2098
+ */
2099
+ interface OrgPort {
2100
+ createOrg(input: CreateOrgPortInput): Effect.Effect<OrgView, OrgError, never>;
2101
+ readTreasury(input: ReadOrgTreasuryInput): Effect.Effect<Account$1, OrgError, never>;
2102
+ listOrgs(input: ListOrgsInput): Effect.Effect<readonly OrgView[], OrgError, never>;
2103
+ listRoles(input: ListOrgRolesInput): Effect.Effect<readonly RoleView[], OrgError, never>;
2104
+ listMembers(input: ListOrgMembersInput): Effect.Effect<readonly MemberView[], OrgError, never>;
2105
+ pendingMembers?(input: ListOrgMembersInput): Effect.Effect<readonly MemberView[], OrgError, never>;
2106
+ inviteMember(input: InviteOrgMemberInput): Effect.Effect<MemberView, OrgError, never>;
2107
+ resendInviteToken?(input: ResendOrgInviteTokenInput): Effect.Effect<MemberView, OrgError, never>;
2108
+ detectAndAcceptPendingInvitations(input: DetectPendingOrgInvitationsInput): Effect.Effect<DetectPendingOrgInvitationsResult$1, OrgError, never>;
2109
+ }
2110
+ interface OrgRolesDeploymentPort {
2111
+ deployRoles(input: DeployOrgRolesInput): Effect.Effect<OrgRolesDeploymentResult, OrgError, never>;
2112
+ grantRole(input: GrantOrgRoleInput): Effect.Effect<MemberView, OrgError, never>;
2113
+ revokeRole(input: RevokeOrgRoleInput): Effect.Effect<void, OrgError, never>;
2114
+ }
2115
+ type SubmitOrgSpendViaPaymentsInput = {
2116
+ readonly orgId: OrgId;
2117
+ readonly input: OrgSpendViaPaymentsInput;
2118
+ readonly amountRaw: string;
2119
+ readonly authority: OrgSpendAuthority;
2120
+ };
2121
+ type SubmitOrgBatchPayrollInput = {
2122
+ readonly orgId: OrgId;
2123
+ readonly from: OrgSpendViaPaymentsInput["from"];
2124
+ readonly runs: readonly {
2125
+ readonly run: OrgPayrollRun;
2126
+ readonly amountRaw: string;
2127
+ }[];
2128
+ readonly authorities: readonly OrgSpendAuthority[];
2129
+ };
2130
+ interface OrgSpendPort {
2131
+ readSpendAuthority(input: ReadOrgSpendAuthorityInput): Effect.Effect<OrgSpendAuthority, OrgError, never>;
2132
+ /**
2133
+ * Leak-safe org spend (G4 · #547; D3 #565 — the one ledger of record): execute
2134
+ * the spend through the payments engine (Roles modifier → CapxulPayments),
2135
+ * write a real `payments` row (`source:"org"`) and read it back as a `Payment`
2136
+ * — the wire carries no `txHash` / Safe / userOp internals. Optional so a
2137
+ * hermetic adapter without a payments-submit lane still compiles; absent ⇒ the
2138
+ * program falls back to a deterministic hermetic `Payment`.
2139
+ */
2140
+ submitSpendViaPayments?(input: SubmitOrgSpendViaPaymentsInput): Effect.Effect<Payment, OrgError, never>;
2141
+ /** Leak-safe org payroll batch (G4 · #547): one MultiSend, one Payment per run. */
2142
+ submitBatchPayroll?(input: SubmitOrgBatchPayrollInput): Effect.Effect<readonly Payment[], OrgError, never>;
2143
+ }
2144
+ //#endregion
2145
+ //#region src/surface/org.d.ts
2146
+ /**
2147
+ * A member's lifecycle status (D9 — unified `Member` with status
2148
+ * `pending | active | revoked | expired`). `pending` = invited (incl. a
2149
+ * non-user emailed into existence) but not yet a provisioned member with an
2150
+ * on-chain grant; `active` = on-chain role granted; `revoked` = offboarded
2151
+ * (on-chain REVOKE fired); `expired` = pending invitation timed out.
2152
+ */
2153
+ type MemberStatus = "pending" | "pending_safe" | "pending_grant" | "active" | "revoked" | "expired";
2154
+ /**
2155
+ * One Org you belong to (canon §C1 "Org list" — name, role, balance).
2156
+ * `role` is the member's role label within THIS org. `treasury` is the M2
2157
+ * `Account` over the Org Safe (D3). `handle` is the globally-unique,
2158
+ * normalized org handle (D10a). Pure record of brand-typed fields — not a
2159
+ * brand.
2160
+ */
2161
+ type OrgView = {
2162
+ readonly id: OrgId;
2163
+ readonly name: string;
2164
+ readonly handle: string;
2165
+ readonly safeAddress: Address; /** The viewing member's own role label within this org. */
2166
+ readonly role: string; /** The Org treasury — the real M2 Account over the Org Safe (D3). */
2167
+ readonly treasury: Account$1; /** #1064: onboarding-collected description + size bucket; null when unset. */
2168
+ readonly bio: string | null;
2169
+ readonly size: string | null; /** #1061 / ADR-0014: logo serving URL resolved at read time; null when unset. */
2170
+ readonly logoUrl: string | null;
2171
+ };
2172
+ interface OrganizationAccount {
2173
+ readonly id: string;
2174
+ readonly address: string | null;
2175
+ readonly balance: Money;
2176
+ readonly available: Money;
2177
+ }
2178
+ interface OrganizationAuditLogItem {
2179
+ readonly id: string;
2180
+ readonly organizationId: string;
2181
+ readonly action: string;
2182
+ readonly actor: string | null;
2183
+ readonly summary: string;
2184
+ readonly createdAt: number;
2185
+ readonly metadata?: Record<string, unknown>;
2186
+ }
2187
+ /**
2188
+ * One member of an Org (canon §C1 "Members" — name/email, role, status; D7/D8).
2189
+ * `personalSafeAddress` is the member-identity key (D7 — Safe-as-identity); it
2190
+ * is `null` while the member is still `pending` (emailed into existence but not
2191
+ * yet provisioned a personal Safe). `email` is the universal entry point (D8).
2192
+ */
2193
+ type MemberView = {
2194
+ readonly orgId: OrgId;
2195
+ readonly email: Email;
2196
+ readonly name: string | null; /** Member-identity key (D7). `null` until the invitee provisions a Safe. */
2197
+ readonly personalSafeAddress: Address | null; /** The member's role label (maps deterministically to the on-chain `roleKey`, D9). */
2198
+ readonly role: string;
2199
+ readonly roleKey: RoleKey | null;
2200
+ readonly status: MemberStatus;
2201
+ readonly grantTxHash: string | null;
2202
+ readonly revokeTxHash: string | null;
2203
+ };
2204
+ /**
2205
+ * A role's on-chain Level-1 spend cap (D4/D5 — physically enforced via Zodiac
2206
+ * Roles + Allowance). `perTx` / `perDay` are `Money`; `toRecipients` scopes the
2207
+ * allowed recipient set. Omitting a field means "unbounded on that axis"
2208
+ * (the Owner role).
2209
+ */
2210
+ type RoleSpendCap = {
2211
+ readonly perTx?: Money;
2212
+ readonly perDay?: Money;
2213
+ readonly toRecipients?: "anyone" | readonly Address[];
2214
+ };
2215
+ /**
2216
+ * The Capxul-owned Role DSL definition (D4). `label` becomes the sticky
2217
+ * bytes32 `roleKey` on-chain. `spend` compiles to Level-1 on-chain Zodiac
2218
+ * conditions; `subAccounts` + `canManage*` compile to Level-2 off-chain Convex
2219
+ * guards (D5).
2220
+ */
2221
+ type RoleDefinition = {
2222
+ readonly label: string;
2223
+ readonly spend?: RoleSpendCap;
2224
+ readonly subAccounts?: {
2225
+ readonly scope: "all" | readonly SubAccountId[];
2226
+ };
2227
+ readonly canManageMembers?: boolean;
2228
+ readonly canManageRoles?: boolean;
2229
+ };
2230
+ /**
2231
+ * One role seeded on an Org (canon §C1 "Roles" — label + caps; D4/D6).
2232
+ * `roleKey` is the on-chain bytes32 role key derived from the label. `definition`
2233
+ * is the full Role DSL entry.
2234
+ */
2235
+ type RoleView = {
2236
+ readonly orgId: OrgId;
2237
+ readonly label: string;
2238
+ readonly roleKey: RoleKey;
2239
+ readonly definition: RoleDefinition;
2240
+ };
2241
+ /** Built-in role templates that seed a new Org at creation (D6). */
2242
+ type OrgTemplate = "Solo" | "Startup" | "Custom";
2243
+ /**
2244
+ * Input to `capxul.createOrg` (S1, D10a, D14). `name` is the display name;
2245
+ * `handle` is the globally-unique normalized handle (`^[a-z0-9-]{3,32}$`, D10a);
2246
+ * `template` seeds the initial role set (D6); `country` is stored unvalidated
2247
+ * (D14 — KYB deferred). For `template: "Custom"`, `roles` carries the authored
2248
+ * `RoleDefinition[]`.
2249
+ */
2250
+ type CreateOrgInput = {
2251
+ readonly name: string;
2252
+ readonly handle: string;
2253
+ readonly template: OrgTemplate;
2254
+ readonly country?: string;
2255
+ readonly roles?: readonly RoleDefinition[];
2256
+ };
2257
+ /**
2258
+ * Input to `org(orgId).invite` (S3, D8). Email is the universal entry point —
2259
+ * inviting an address that is not yet a Capxul user auto-creates a `pending`
2260
+ * membership that resolves on sign-in (the virality loop). `role` names the
2261
+ * role label the invitee is granted on accept.
2262
+ */
2263
+ type InviteMemberInput = {
2264
+ readonly email: string;
2265
+ readonly role: string;
2266
+ };
2267
+ type ResendInviteTokenInput = {
2268
+ readonly email: string;
2269
+ };
2270
+ /**
2271
+ * Input to `org(orgId).removeMember` (S3, D8). Keyed on the member's personal
2272
+ * Safe address (D7 — Safe-as-identity). Drives the on-chain REVOKE + Convex
2273
+ * mirror.
2274
+ */
2275
+ type RemoveMemberInput = {
2276
+ readonly memberSafeAddress: Address;
2277
+ };
2278
+ /**
2279
+ * Input to `org(orgId).assignRole` (S3, D7/D9). Keyed on the member's personal
2280
+ * Safe address (D7). Drives the on-chain GRANT + Convex mirror; the `role`
2281
+ * label maps deterministically to the on-chain `roleKey`.
2282
+ */
2283
+ type AssignRoleInput = {
2284
+ readonly memberSafeAddress: Address;
2285
+ readonly role: string;
2286
+ };
2287
+ /**
2288
+ * Input to `org(orgId).spendViaPayments` (G4 · #547). The LEAK-SAFE org spend:
2289
+ * delegates `org.spend` to the payments engine WITH the member's org role
2290
+ * authority and returns a `Payment`, not a `txHash`. `to` is a VALIDATED
2291
+ * recipient ref (handle / email / payee id / org handle) — never a raw
2292
+ * `Address` (the legacy address-keyed `org.spend` lane was hard-removed in D3
2293
+ * #565 when `orgSpends` was folded into the one `payments` ledger).
2294
+ * `from` is the Level-2 sub-account envelope the spend draws from (D5).
2295
+ */
2296
+ type OrgSpendViaPaymentsInput = {
2297
+ readonly from: SubAccountId; /** Validated recipient ref (handle/email/payee/org) — never a raw address. */
2298
+ readonly to: Ref$1;
2299
+ readonly amount: Money; /** Full EIP-712 payment document; hashed + stored, committed on-chain. */
2300
+ readonly document?: PaymentDocumentEnvelopeV1;
2301
+ readonly timing?: PaymentTiming;
2302
+ readonly paymentType?: PaymentType;
2303
+ };
2304
+ /**
2305
+ * One run in an `org(orgId).batchPayroll` batch (G4 · #547): a validated
2306
+ * recipient, an amount, and an optional payslip document. Each run is gated
2307
+ * independently against the role's per-tx / per-day / recipient conditions.
2308
+ */
2309
+ type OrgPayrollRun = {
2310
+ /** Validated recipient ref (handle/email/payee/org) — never a raw address. */readonly to: Ref$1;
2311
+ readonly amount: Money;
2312
+ readonly timing?: PaymentTiming; /** The payslip — an EIP-712 payment document, committed by `documentHash`. */
2313
+ readonly payslip?: PaymentDocumentEnvelopeV1;
2314
+ };
2315
+ /**
2316
+ * Input to `org(orgId).batchPayroll` (G4 · #547). Pays N employees in one
2317
+ * MultiSend through the Roles modifier; each carries a payslip and settles as
2318
+ * `paymentType = payroll`. Every run is gated; an over-cap run REJECTS the
2319
+ * whole batch (no partial treasury drain). Returns one leak-safe `Payment` per
2320
+ * run.
2321
+ */
2322
+ type OrgBatchPayrollInput = {
2323
+ readonly from: SubAccountId;
2324
+ readonly runs: readonly OrgPayrollRun[];
2325
+ };
2326
+ type DetectPendingOrgInvitationsResult = {
2327
+ readonly matched: readonly OrgId[];
2328
+ };
2329
+ /**
2330
+ * Entity-scoped Org method bundle, returned by `capxul.org(orgId)`. Every
2331
+ * method names the entity implicitly via the closed-over `orgId` (D13 — no
2332
+ * stateful active context). `treasury()` returns the real M2 `Account` over
2333
+ * the Org Safe (D3).
2334
+ */
2335
+ interface PayrollRosterLine {
2336
+ readonly id: string;
2337
+ readonly employee: Ref$1;
2338
+ readonly amount: Money;
2339
+ readonly timing: PaymentTiming;
2340
+ readonly status: "active" | "paused" | "ended";
2341
+ }
2342
+ interface PayrollPayslipTemplate {
2343
+ readonly title: string;
2344
+ readonly memo?: string;
2345
+ }
2346
+ interface PayrollRosterAddInput {
2347
+ readonly employee: Ref$1;
2348
+ readonly amount: Money;
2349
+ readonly timing: PaymentTiming;
2350
+ readonly payslipTemplate?: PaymentDocumentEnvelopeV1 | PayrollPayslipTemplate;
2351
+ }
2352
+ interface PayrollRunInput {
2353
+ readonly from: SubAccountId;
2354
+ readonly period: string;
2355
+ }
2356
+ interface PayrollMethods {
2357
+ readonly roster: {
2358
+ add(input: PayrollRosterAddInput, options?: {
2359
+ readonly signal?: AbortSignal;
2360
+ }): Promise<CapxulResult<PayrollRosterLine>>;
2361
+ list(options?: {
2362
+ readonly signal?: AbortSignal;
2363
+ }): Promise<CapxulResult<readonly PayrollRosterLine[]>>;
2364
+ update(rosterLineId: string, input: Partial<PayrollRosterAddInput>, options?: {
2365
+ readonly signal?: AbortSignal;
2366
+ }): Promise<CapxulResult<PayrollRosterLine>>;
2367
+ remove(rosterLineId: string, options?: {
2368
+ readonly signal?: AbortSignal;
2369
+ }): Promise<CapxulResult<PayrollRosterLine>>;
2370
+ };
2371
+ run(input: PayrollRunInput, options?: {
2372
+ readonly signal?: AbortSignal;
2373
+ }): Promise<CapxulResult<readonly Payment[]>>;
2374
+ }
2375
+ interface OrgScopedMethods extends ActorRelationshipMethods {
2376
+ /** Observe the durable, leak-safe lifecycle for this Organization only. */
2377
+ getLifecycle(options?: {
2378
+ readonly signal?: AbortSignal;
2379
+ }): Promise<CapxulResult<OrgLifecycle>>;
2380
+ /** Explicitly resume this Organization's durable setup lane. */
2381
+ retrySetup(options?: {
2382
+ readonly signal?: AbortSignal;
2383
+ }): Promise<CapxulResult<OrgLifecycle>>;
2384
+ /** The Org treasury — the real M2 Account over the Org Safe (D3). */
2385
+ treasury(options?: {
2386
+ readonly signal?: AbortSignal;
2387
+ }): Promise<CapxulResult<Account$1>>;
2388
+ readonly account: {
2389
+ get(options?: {
2390
+ readonly signal?: AbortSignal;
2391
+ }): Promise<CapxulResult<OrganizationAccount>>;
2392
+ };
2393
+ members(options?: {
2394
+ readonly signal?: AbortSignal;
2395
+ }): Promise<CapxulResult<readonly MemberView[]>>;
2396
+ roles(options?: {
2397
+ readonly signal?: AbortSignal;
2398
+ }): Promise<CapxulResult<readonly RoleView[]>>;
2399
+ deployRoles(options?: {
2400
+ readonly signal?: AbortSignal;
2401
+ }): Promise<CapxulResult<readonly RoleView[]>>;
2402
+ invite(input: InviteMemberInput, options?: {
2403
+ readonly signal?: AbortSignal;
2404
+ }): Promise<CapxulResult<MemberView>>;
2405
+ removeMember(input: RemoveMemberInput, options?: {
2406
+ readonly signal?: AbortSignal;
2407
+ }): Promise<CapxulResult<void>>;
2408
+ assignRole(input: AssignRoleInput, options?: {
2409
+ readonly signal?: AbortSignal;
2410
+ }): Promise<CapxulResult<MemberView>>;
2411
+ /**
2412
+ * Leak-safe org spend (G4 · #547; D3 #565 — the one ledger of record): execute
2413
+ * the spend through the payments engine with the member's org role authority
2414
+ * and return a `Payment` (no `to: Address`, no `txHash`, no Safe / userOp
2415
+ * internals). Writes a real `payments` row (`source:"org"`).
2416
+ */
2417
+ spendViaPayments(input: OrgSpendViaPaymentsInput, options?: {
2418
+ readonly signal?: AbortSignal;
2419
+ }): Promise<CapxulResult<Payment>>;
2420
+ /**
2421
+ * Org payroll batch (G4 · #547): pay N employees in one MultiSend through the
2422
+ * Roles modifier, each with a payslip. Every run is gated; an over-cap run
2423
+ * rejects the whole batch. Returns one leak-safe `Payment` per run.
2424
+ */
2425
+ batchPayroll(input: OrgBatchPayrollInput, options?: {
2426
+ readonly signal?: AbortSignal;
2427
+ }): Promise<CapxulResult<readonly Payment[]>>;
2428
+ readonly payroll: PayrollMethods;
2429
+ auditLog(options?: {
2430
+ readonly signal?: AbortSignal;
2431
+ }): Promise<CapxulResult<readonly OrganizationAuditLogItem[]>>;
2432
+ }
2433
+ type OrgsMethod = {
2434
+ (options?: {
2435
+ readonly signal?: AbortSignal;
2436
+ }): Promise<CapxulResult<readonly OrgView[]>>;
2437
+ detectAndAcceptPendingInvitations(options?: {
2438
+ readonly signal?: AbortSignal;
2439
+ }): Promise<CapxulResult<DetectPendingOrgInvitationsResult>>;
2440
+ };
2441
+ /**
2442
+ * Top-level Org method bundle, exposed at `client.org` / `client.orgs` /
2443
+ * `client.createOrg`. `org(orgId)` resolves the entity-scoped bundle (D13).
2444
+ */
2445
+ interface OrgMethods {
2446
+ createOrg(input: CreateOrgInput, options?: {
2447
+ readonly signal?: AbortSignal;
2448
+ }): Promise<CapxulResult<OrgView>>;
2449
+ readonly orgs: OrgsMethod;
2450
+ /** Resolve the entity-scoped bundle for a specific Org (D13). */
2451
+ org(orgId: OrgId): OrgScopedMethods;
2452
+ }
2453
+ //#endregion
2454
+ //#region src/surface/current-user.d.ts
2455
+ interface CurrentUserContext {
2456
+ readonly user: {
2457
+ readonly id: string;
2458
+ readonly email: string;
2459
+ readonly displayName: string | null;
2460
+ readonly handle: string | null;
2461
+ readonly paymentLink: {
2462
+ readonly handle: string;
2463
+ readonly url: string;
2464
+ } | null;
2465
+ };
2466
+ readonly personalAccount: {
2467
+ readonly id: string;
2468
+ readonly address: string | null;
2469
+ } | null;
2470
+ readonly organizations: readonly {
2471
+ readonly id: string;
2472
+ readonly name: string;
2473
+ readonly handle: string;
2474
+ readonly role: string;
2475
+ readonly account: {
2476
+ readonly id: string;
2477
+ readonly address: string | null;
2478
+ } | null;
2479
+ }[];
2480
+ }
2481
+ interface CurrentUserMethods {
2482
+ get(options?: {
2483
+ readonly signal?: AbortSignal;
2484
+ }): Promise<CapxulResult<CurrentUserContext>>;
2485
+ }
2486
+ //#endregion
2487
+ //#region src/surface/media.d.ts
2488
+ interface MediaMethods {
2489
+ uploadImage(blob: Blob, options?: {
2490
+ readonly signal?: AbortSignal;
2491
+ }): Promise<CapxulResult<{
2492
+ readonly storageId: string;
2493
+ }>>;
2494
+ setProfileImage(input: {
2495
+ readonly storageId: string;
2496
+ }, options?: {
2497
+ readonly signal?: AbortSignal;
2498
+ }): Promise<CapxulResult<{
2499
+ readonly imageUrl: string | null;
2500
+ }>>;
2501
+ setOrgLogo(input: {
2502
+ readonly orgId: string;
2503
+ readonly storageId: string;
2504
+ }, options?: {
2505
+ readonly signal?: AbortSignal;
2506
+ }): Promise<CapxulResult<{
2507
+ readonly logoUrl: string | null;
2508
+ }>>;
2509
+ }
2510
+ //#endregion
2511
+ //#region src/contract/system.d.ts
2512
+ /** What `system:health` answers. */
2513
+ interface SystemHealth {
2514
+ /** The nonce the caller sent, as the backend saw it. */
2515
+ readonly nonce: string;
2516
+ /** Deployment that answered, e.g. `little-sandpiper-974`. */
2517
+ readonly deployment: string;
2518
+ /** Backend clock at execution (epoch ms). */
2519
+ readonly at: number;
2520
+ }
2521
+ //#endregion
2522
+ //#region src/surface/system.d.ts
2523
+ interface SystemMethods {
2524
+ health(nonce: string, options?: {
2525
+ readonly signal?: AbortSignal;
2526
+ }): Promise<CapxulResult<SystemHealth>>;
2527
+ }
2528
+ //#endregion
2529
+ //#region src/surface/sub-accounts.d.ts
2530
+ interface SubAccountsMethods {
2531
+ create(accountId: AccountId, input: {
2532
+ readonly name: string;
2533
+ }, options?: {
2534
+ readonly signal?: AbortSignal;
2535
+ }): Promise<CapxulResult<SubAccount>>;
2536
+ get(subAccountId: SubAccountId, options?: {
2537
+ readonly signal?: AbortSignal;
2538
+ }): Promise<CapxulResult<SubAccount | null>>;
2539
+ list(accountId: AccountId, options?: {
2540
+ readonly signal?: AbortSignal;
2541
+ }): Promise<CapxulResult<readonly SubAccount[]>>;
2542
+ rename(subAccountId: SubAccountId, name: string, options?: {
2543
+ readonly signal?: AbortSignal;
2544
+ }): Promise<CapxulResult<SubAccount>>;
2545
+ delete(subAccountId: SubAccountId, options?: {
2546
+ readonly signal?: AbortSignal;
2547
+ }): Promise<CapxulResult<void>>;
2548
+ transfer(input: TransferInput, options?: {
2549
+ readonly signal?: AbortSignal;
2550
+ }): Promise<CapxulResult<TransferResult>>;
2551
+ }
2552
+ //#endregion
2553
+ //#region src/surface/_shared/effect-actor-bridge.d.ts
2554
+ type IdentityFacadeVerb = "requestCode" | "verifyCode" | "signOut" | "createOrganization" | "completePersonal" | "retry";
2555
+ //#endregion
2556
+ //#region src/surface/create-capxul-client.d.ts
2557
+ type OrganizationSetupProofReceipt = {
2558
+ readonly state: "submitted";
2559
+ readonly orgId: string;
2560
+ readonly chainId: number;
2561
+ readonly signerEoa: string;
2562
+ readonly founderAccount: string;
2563
+ readonly organizationAccount: string;
2564
+ readonly userOperationHash: string;
2565
+ readonly submittedAt: number;
2566
+ readonly attempt: number;
2567
+ } | {
2568
+ readonly state: "confirmed";
2569
+ readonly orgId: string;
2570
+ readonly chainId: number;
2571
+ readonly signerEoa: string;
2572
+ readonly founderAccount: string;
2573
+ readonly organizationAccount: string;
2574
+ readonly userOperationHash: string;
2575
+ readonly submittedAt: number;
2576
+ readonly attempt: number;
2577
+ readonly confirmationTransactionHash: string;
2578
+ readonly readyAt: number;
2579
+ };
2580
+ type OrganizationSetupProofMethods = {
2581
+ readonly getProofReceipt: (orgId: string) => Promise<CapxulResult<OrganizationSetupProofReceipt | null>>;
2582
+ };
2583
+ type IdentityRuntimeSendResult = {
2584
+ readonly ok: true;
2585
+ readonly state: IdentityState;
2586
+ } | {
2587
+ readonly ok: false;
2588
+ readonly refused: CapxulErrorCode;
2589
+ readonly state: IdentityState;
2590
+ };
2591
+ type IdentityProfileDetails = {
2592
+ readonly displayName: string;
2593
+ readonly country: string;
2594
+ readonly username?: string;
2595
+ };
2596
+ interface IdentityRuntime {
2597
+ readonly snapshot: () => IdentityState;
2598
+ readonly subscribe: IdentityActor["subscribe"];
2599
+ readonly subscribeTransitions: IdentityActor["subscribeTransitions"];
2600
+ readonly send: (event: IdentityEvent, controls?: InvocationControls) => Promise<IdentityRuntimeSendResult>;
2601
+ readonly completeProfile: (profile: IdentityProfileDetails, controls?: InvocationControls) => Promise<{
2602
+ readonly ok: true;
2603
+ } | {
2604
+ readonly ok: false;
2605
+ readonly reason: CapxulErrorCode;
2606
+ }>;
2607
+ /** @internal One facade bridge; optional only for pre-S2 consumer test doubles. */
2608
+ readonly runFacade?: <T>(verb: IdentityFacadeVerb, controls: InvocationControls | undefined, run: (controls: InvocationControls) => Promise<T>) => Promise<T>;
2609
+ }
2610
+ interface CapxulClient {
2611
+ readonly auth: AuthMethods;
2612
+ readonly smartAccount: SmartAccountMethods;
2613
+ readonly identity: IdentityMethods;
2614
+ /**
2615
+ * Liveness surface (#1149 proof lane): `health(nonce)` round-trips a nonce
2616
+ * through the configured deployment. The only method here that is useful
2617
+ * before sign-in, and the only one whose whole point is that the answer
2618
+ * came from the backend rather than from this process.
2619
+ */
2620
+ readonly system: SystemMethods;
2621
+ /**
2622
+ * Consumer-facing account readiness surface (issue #159 · AC1+AC3).
2623
+ * Exactly `getStatus` + `ensureReady`; the `_internal.account`
2624
+ * namespace with `provision` + `deploySafe` lands in sibling #161.
2625
+ */
2626
+ readonly account: AccountMethods;
2627
+ /**
2628
+ * Consumer-facing logical Account money read (M2 Slice S1a · #265).
2629
+ * Returns `{ balance, available }` as `Money` — never wei or token units.
2630
+ */
2631
+ readonly accounts: AccountsMethods;
2632
+ readonly currentUser: CurrentUserMethods;
2633
+ readonly me: MeMethods;
2634
+ readonly handles: HandlesMethods;
2635
+ readonly payees: PayeesMethods;
2636
+ readonly targets: TargetsMethods;
2637
+ readonly destinations: DestinationsMethods;
2638
+ /**
2639
+ * Direct Payments surface (G2 · #545). `pay` records a validated-recipient
2640
+ * payment; `list`/`get` read the ledger; `markSettled` is the host-execution
2641
+ * callback.
2642
+ */
2643
+ readonly payments: PaymentsMethods;
2644
+ readonly activity: ActivityMethods;
2645
+ readonly offramp: OfframpMethods;
2646
+ /** Payment document verification (G2 · #545): re-derive the EIP-712 hash. */
2647
+ readonly paymentDocuments: PaymentDocumentsMethods;
2648
+ /**
2649
+ * Media surface (#1061 / ADR-0014): profile-image + org-logo upload/record.
2650
+ */
2651
+ readonly media: MediaMethods;
2652
+ /** Sub-account lifecycle (M2 Slice S2a · #267). Transfer lands in S2b. */
2653
+ readonly subAccounts: SubAccountsMethods;
2654
+ /**
2655
+ * Organization domain surface (canon `org-domain-model.md` §C2/§C3, D13).
2656
+ * `createOrg(input)` creates an Org; `orgs()` lists the Orgs you belong to;
2657
+ * `org(orgId)` resolves the entity-scoped bundle (treasury / members / roles
2658
+ * / invite / removeMember / assignRole / spend). Explicit entity scoping —
2659
+ * NO stateful active context (D13). RED until the S1→S4 slices fill it.
2660
+ */
2661
+ readonly createOrg: OrgMethods["createOrg"];
2662
+ readonly orgs: OrgMethods["orgs"];
2663
+ readonly org: OrgMethods["org"];
2664
+ /**
2665
+ * Internal identity integration runtime. It is consumed by
2666
+ * `@capxul/sdk-react`, not exported as the actor substrate itself.
2667
+ *
2668
+ * @internal-use
2669
+ */
2670
+ readonly _internal: {
2671
+ readonly identity: IdentityRuntime;
2672
+ /**
2673
+ * Resolved bootstrap for this client instance (chain, auth URLs, etc.).
2674
+ * Off the public surface per production-surface-policy.md (#31).
2675
+ */
2676
+ readonly bootstrap: BootstrapResolution;
2677
+ /**
2678
+ * Dev-only faucet bundle (production-surface-policy.md). `fund` lives here,
2679
+ * NOT on the public `client.accounts` surface.
2680
+ */
2681
+ readonly accounts: AccountsFaucetMethods; /** Quarantined Reference-harness evidence; never a product Organization method. */
2682
+ readonly organizationSetup: OrganizationSetupProofMethods; /** Telemetry port for error reporting. Used by React hooks to report errors before throwing. */
2683
+ readonly telemetry?: TelemetryPort;
2684
+ readonly close?: () => Promise<void>;
2685
+ };
2686
+ }
2687
+ interface CreateCapxulClientInput {
2688
+ /**
2689
+ * The 10-port `FlowPorts` bundle. The identity actor uses its auth, clock,
2690
+ * identity, smart-account, and telemetry seams internally; the remaining
2691
+ * method bundles consume the same canonical port authorities.
2692
+ */
2693
+ readonly ports: FlowPorts;
2694
+ /**
2695
+ * Bootstrap resolution for this client instance. The factory closes over
2696
+ * `bootstrap.chainId` internally; consumers do not pass a standalone
2697
+ * chainId and no method boundary accepts one.
2698
+ */
2699
+ readonly bootstrap: BootstrapResolution;
2700
+ /**
2701
+ * Optional AuthCachePort. When omitted, `detectAuthCacheAdapter()` selects
2702
+ * the appropriate per-environment adapter (Browser/FileSystem/InMemory).
2703
+ */
2704
+ readonly authCache?: AuthCachePort;
2705
+ /**
2706
+ * Optional AbortSignal reserved for callers that coordinate client lifetime.
2707
+ */
2708
+ readonly signal?: AbortSignal;
2709
+ /**
2710
+ * OTP TTL window in ms. Default 300_000 (5 min).
2711
+ */
2712
+ readonly otpTtlMs?: number;
2713
+ /**
2714
+ * Optional per-call timeout for invoked auth requests.
2715
+ */
2716
+ readonly invokeTimeoutMs?: number;
2717
+ /**
2718
+ * Init-time account readiness target (issue #159 · AC4). The factory
2719
+ * closes over this so `client.account.{getStatus,ensureReady}` don't
2720
+ * need to take a per-call requirement arg. REQUIRED — there is no
2721
+ * hidden default. Consumers building flows that never need a smart
2722
+ * account pass `"none"`; flows that want a counterfactual deposit
2723
+ * address pass `"counterfactual"`; flows that need an on-chain Safe
2724
+ * pass `"deployed"` (deploy path lands in sibling #161).
2725
+ */
2726
+ readonly requirement: AccountRequirement;
2727
+ /**
2728
+ * Consumer-held signer (backend-orchestrated-deploy.md). Required for
2729
+ * `requirement: "deployed"` flows: `provision` reads `getAddress()` and the
2730
+ * deploy path signs the backend's SafeOp digest via `signUserOpHash()`. The
2731
+ * backend orchestrates build + gas + paymaster + submit — the client never
2732
+ * holds an RPC URL, a gas-sponsorship policy, or a bundler.
2733
+ */
2734
+ readonly signer?: CapxulSigner;
2735
+ /**
2736
+ * Optional live Org-deploy lane (canon D10 SDK-orchestrated Org Safe deploy +
2737
+ * D3 RPC treasury). When supplied, `client.createOrg` / `org(id).treasury`
2738
+ * run the live path (real deploy + on-chain balance); when omitted, the
2739
+ * hermetic `$0` path runs (a fresh Org has no on-chain funds). The adapter
2740
+ * that CONSTRUCTS this port (deployer key + RPC + authenticated Convex seam)
2741
+ * is wired by the CLI deploy-stack; the factory only threads it through.
2742
+ */
2743
+ readonly orgDeploymentPort?: OrgPort;
2744
+ /** Locked D6 data-port name. Prefer over `orgDeploymentPort` in new code. */
2745
+ readonly orgPort?: OrgPort;
2746
+ /** S2 deploy/grant/revoke port. S2 uses deploy; S3 adds grant/revoke. */
2747
+ readonly orgRolesDeploymentPort?: OrgRolesDeploymentPort;
2748
+ /** S4 treasury-spend authority + submit port. */
2749
+ readonly orgSpendPort?: OrgSpendPort;
2750
+ /**
2751
+ * Internal Organization lifecycle capability. The Core SDK owns its
2752
+ * choreography; production composition supplies the provider/backend steps.
2753
+ */
2754
+ readonly organizationSetup?: OrganizationSetupOps;
2755
+ readonly orgDeploymentConfig?: SafeDeploymentConfig;
2756
+ /** Internal runner carrying the composition root's logger/tracer references. */
2757
+ readonly effectRunner?: {
2758
+ readonly runSync: <A, E>(effect: Effect.Effect<A, E>) => A;
2759
+ readonly runPromise: <A, E>(effect: Effect.Effect<A, E>) => Promise<A>;
2760
+ };
2761
+ }
2762
+ //#endregion
2763
+ export { InsightsSummary as $, OrgSetupStep as $t, PayrollRosterLine as A, PaymentMoney as At, ActorProfileMethods as B, RecipientResolutionKind as Bt, OrgTemplate as C, PayeesMethods as Ct, PayrollMethods as D, PaymentDocumentRender as Dt, OrganizationAuditLogItem as E, PaymentDocumentRef as Et, RoleSpendCap as F, PaymentsMethods as Ft, AddressBookAddInput as G, TargetsMethods as Gt, ActorRequest as H, Ref$1 as Ht, RoleView as I, PaymentsPayInput as It, AddressBookMethods as J, isSettingUpLifecycle as Jt, AddressBookEntry as K, AccountLifecycle as Kt, AccountsMethods as L, PaymentsPayoutInput as Lt, RemoveMemberInput as M, PaymentStatus as Mt, ResendInviteTokenInput as N, PaymentTiming as Nt, PayrollPayslipTemplate as O, PaymentDocumentVerification as Ot, RoleDefinition as P, PaymentType as Pt, InsightsMethods as Q, OrgLifecycle as Qt, AccountMethods as R, PaymentsWithdrawInput as Rt, OrgSpendViaPaymentsInput as S, Payee as St, OrganizationAccount as T, PaymentDocumentKind as Tt, ActorRequestIssueInput as U, ResolvedTarget as Ut, ActorRelationshipMethods as V, ReconciliationEntry as Vt, ActorRequestsMethods as W, TargetReference as Wt, InboxItem as X, SmartAccountMethods as Xt, InboxApproveInput as Y, IdentityMethods as Yt, InboxMethods as Z, AuthMethods as Zt, MemberView as _, InvocationControls as _n, MeProfile as _t, IdentityRuntimeSendResult as a, TelemetryEvent as an, DepositInstructions as at, OrgPayrollRun as b, OfframpQuoteInput as bt, SystemHealth as c, TelemetryPort as cn, DestinationKind as ct, CurrentUserMethods as d, IdentityState as dn, DestinationRail as dt, WireObservationContext as en, ActivityItem as et, AssignRoleInput as f, OrgLane as fn, DestinationRemoveInput as ft, MemberStatus as g, IdentityTransition as gn, MeMethods as gt, InviteMemberInput as h, destination as hn, HandlesMethods as ht, IdentityRuntime as i, CapxulEnv as in, ActorReference as it, PayrollRunInput as j, PaymentSettlementInput as jt, PayrollRosterAddInput as k, PaymentDocumentsMethods as kt, MediaMethods as l, Destination$1 as ln, DestinationListInput as lt, DetectPendingOrgInvitationsResult as m, StateLabel as mn, FinancialOpsMethods as mt, CreateCapxulClientInput as n, TransferInput as nn, ActivityMethods as nt, SubAccountsMethods as o, TelemetryGroupInput as on, Destination as ot, CreateOrgInput as p, Readiness as pn, DestinationsMethods as pt, AddressBookLabelInput as q, AccountSetupStep as qt, IdentityProfileDetails as r, TransferResult as rn, ActivityPage as rt, SystemMethods as s, TelemetryIdentifyInput as sn, DestinationAddInput as st, CapxulClient as t, TransferEndpoint as tn, ActivityListParams as tt, CurrentUserContext as u, IdentityEvent as un, DestinationPayload as ut, OrgBatchPayrollInput as v, OfframpMethods as vt, OrgView as w, Payment as wt, OrgScopedMethods as x, OfframpStatus as xt, OrgMethods as y, OfframpQuote as yt, ActorProfile as z, RecipientResolution as zt };
2764
+ //# sourceMappingURL=create-capxul-client-C7H5b68l.d.mts.map