@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.
- package/README.md +121 -6
- package/dist/{InMemoryAuthCacheAdapter-v5W-XB5M.mjs → InMemoryAuthCacheAdapter-Dr1sEd9y.mjs} +36 -16
- package/dist/InMemoryAuthCacheAdapter-Dr1sEd9y.mjs.map +1 -0
- package/dist/create-capxul-client-C7H5b68l.d.mts +2764 -0
- package/dist/create-capxul-client-C7H5b68l.d.mts.map +1 -0
- package/dist/create-capxul-client-DiqVIxsV.mjs +6980 -0
- package/dist/create-capxul-client-DiqVIxsV.mjs.map +1 -0
- package/dist/index.d.mts +119 -2020
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +2464 -6308
- package/dist/index.mjs.map +1 -1
- package/dist/node/index.d.mts +3 -6
- package/dist/node/index.d.mts.map +1 -1
- package/dist/node/index.mjs +27 -27
- package/dist/node/index.mjs.map +1 -1
- package/dist/signer-CJT0pPiO.d.mts +301 -0
- package/dist/signer-CJT0pPiO.d.mts.map +1 -0
- package/dist/testing/index.d.mts +54 -0
- package/dist/testing/index.d.mts.map +1 -0
- package/dist/testing/index.mjs +1068 -0
- package/dist/testing/index.mjs.map +1 -0
- package/package.json +17 -18
- package/dist/InMemoryAuthCacheAdapter-v5W-XB5M.mjs.map +0 -1
- package/dist/index-CTXgQ_xR.d.mts +0 -158
- package/dist/index-CTXgQ_xR.d.mts.map +0 -1
- package/dist/ports/safe-deployment.d.mts +0 -2
- package/dist/ports/safe-deployment.mjs +0 -38
- package/dist/ports/safe-deployment.mjs.map +0 -1
- package/dist/safe-deployment-D3k9yndM.d.mts +0 -136
- package/dist/safe-deployment-D3k9yndM.d.mts.map +0 -1
- package/dist/signer-DqDtJU1l.d.mts +0 -145
- 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
|