@nangohq/types 0.71.4 → 0.71.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/dist/account/api.d.ts +49 -2
  2. package/dist/action/api.d.ts +4 -0
  3. package/dist/admin/http.api.d.ts +1 -1
  4. package/dist/agent/api.d.ts +88 -0
  5. package/dist/agent/connections.d.ts +44 -0
  6. package/dist/agent/mcp.api.d.ts +28 -0
  7. package/dist/agent/session.d.ts +20 -0
  8. package/dist/agent/toolSearch.d.ts +34 -0
  9. package/dist/agent/toolset.d.ts +43 -0
  10. package/dist/api-keys/auth.d.ts +2 -0
  11. package/dist/api-keys/scopes.d.ts +9 -4
  12. package/dist/api.endpoints.d.ts +9 -7
  13. package/dist/audit-trail/api.d.ts +21 -8
  14. package/dist/audit-trail/event.d.ts +135 -15
  15. package/dist/audit-trail/metadata.d.ts +99 -0
  16. package/dist/auth/api.d.ts +1 -1
  17. package/dist/auth/http.api.d.ts +11 -40
  18. package/dist/authz/types.d.ts +1 -1
  19. package/dist/billing/types.d.ts +56 -10
  20. package/dist/connection/api/get.d.ts +1 -1
  21. package/dist/connection/api/metadata.d.ts +8 -2
  22. package/dist/environment/api/index.d.ts +92 -1
  23. package/dist/environment/api/webhook.d.ts +1 -0
  24. package/dist/environment/db.d.ts +2 -0
  25. package/dist/function/trigger.d.ts +61 -0
  26. package/dist/functions/api.d.ts +35 -0
  27. package/dist/index.d.ts +10 -2
  28. package/dist/keystore/index.d.ts +10 -2
  29. package/dist/logs/messages.d.ts +24 -3
  30. package/dist/meta/api.d.ts +1 -0
  31. package/dist/mfa/api.d.ts +2 -7
  32. package/dist/mfa/credential.d.ts +7 -0
  33. package/dist/mfa/db.d.ts +1 -0
  34. package/dist/persist/api.d.ts +1 -1
  35. package/dist/plans/db.d.ts +21 -1
  36. package/dist/plans/http.api.d.ts +109 -0
  37. package/dist/providers/provider.d.ts +1 -0
  38. package/dist/pubsub/events.d.ts +2 -2
  39. package/dist/runner/sdk.d.ts +1 -1
  40. package/dist/sharedCredentials/api.d.ts +2 -0
  41. package/dist/sharedCredentials/db.d.ts +1 -0
  42. package/dist/sharedCredentials/dto.d.ts +1 -1
  43. package/dist/stripe/http.api.d.ts +3 -0
  44. package/dist/sync/api.d.ts +1 -1
  45. package/dist/usage/index.d.ts +1 -1
  46. package/dist/user/api.d.ts +5 -1
  47. package/dist/web/env.d.ts +3 -0
  48. package/dist/webhooks/api.d.ts +2 -1
  49. package/package.json +1 -1
@@ -1,27 +1,101 @@
1
+ import type { ApiKeyUpdatedMetadata, AppAuthLoginMetadata, AuditTrailFiltersMetadata, AuditTrailQueriedMetadata, BillingPaymentMethodRemovedMetadata, BillingPlanChangedMetadata, BillingSpendAlertChangedMetadata, ConnectionMetadata, ConnectionUpdatedMetadata, EnvironmentCreatedMetadata, EnvironmentUpdatedMetadata, EnvironmentVariablesChangedMetadata, EnvironmentWebhookMetadata, FunctionDeletedMetadata, FunctionDeployedMetadata, FunctionUpgradedMetadata, IntegrationProviderMetadata, IntegrationUpdatedMetadata, MemberInvitedMetadata, MemberRoleChangedMetadata, MfaVerifiedMetadata, SyncBaseMetadata, SyncFrequencyChangedMetadata, SyncTriggeredMetadata, SyncVariantMetadata, TeamUpdatedMetadata, UserUpdatedMetadata } from './metadata.js';
1
2
  export type AuditTrailVersion = '2026-07-16';
2
- export type AuditActorType = 'user' | 'api_key' | 'system' | 'anonymous';
3
+ export type AuditActorType = 'user' | 'api_key' | 'public_key' | 'connect_session' | 'anonymous' | 'unknown';
3
4
  export type AuditOutcome = 'success' | 'failure' | 'denied';
5
+ export type AuditViaType = 'impersonation';
4
6
  export type AuditInterface = 'api' | 'mcp';
5
7
  interface AuditEventTable {
6
- connection: 'created' | 'updated' | 'metadata_updated' | 'refreshed' | 'deleted';
7
- sync: 'enabled' | 'disabled' | 'paused' | 'started' | 'triggered' | 'cancelled' | 'frequency_changed' | 'variant_created' | 'variant_deleted';
8
- function: 'deployed' | 'upgraded' | 'deleted';
9
- integration: 'created' | 'updated' | 'deleted';
10
- api_key: 'created' | 'updated' | 'deleted';
11
- member: 'invited' | 'invite_accepted' | 'invite_declined' | 'invite_revoked' | 'role_changed' | 'removed';
12
- team: 'updated';
13
- user: 'updated';
14
- environment: 'created' | 'updated' | 'variables_changed' | 'webhook_urls_changed' | 'deleted';
15
- app_auth: 'login' | 'logout' | 'signup' | 'password_changed' | 'password_reset';
16
- mfa: 'enrolled' | 'enabled' | 'disabled' | 'verified' | 'recovery_regenerated';
17
- billing: 'plan_changed' | 'trial_extended' | 'details_changed' | 'payment_method_added' | 'payment_method_removed';
8
+ connection: {
9
+ created: ConnectionMetadata;
10
+ updated: ConnectionUpdatedMetadata;
11
+ metadata_updated: ConnectionMetadata;
12
+ refreshed: ConnectionMetadata;
13
+ deleted: ConnectionMetadata;
14
+ };
15
+ sync: {
16
+ enabled: SyncBaseMetadata;
17
+ disabled: SyncBaseMetadata;
18
+ paused: SyncBaseMetadata;
19
+ started: SyncBaseMetadata;
20
+ triggered: SyncTriggeredMetadata;
21
+ cancelled: SyncBaseMetadata;
22
+ frequency_changed: SyncFrequencyChangedMetadata;
23
+ variant_created: SyncVariantMetadata;
24
+ variant_deleted: SyncVariantMetadata;
25
+ };
26
+ function: {
27
+ deployed: FunctionDeployedMetadata;
28
+ upgraded: FunctionUpgradedMetadata;
29
+ deleted: FunctionDeletedMetadata;
30
+ };
31
+ integration: {
32
+ created: IntegrationProviderMetadata;
33
+ updated: IntegrationProviderMetadata & IntegrationUpdatedMetadata;
34
+ deleted: IntegrationProviderMetadata;
35
+ };
36
+ api_key: {
37
+ created: ApiKeyUpdatedMetadata;
38
+ updated: ApiKeyUpdatedMetadata;
39
+ deleted: never;
40
+ };
41
+ member: {
42
+ invited: MemberInvitedMetadata;
43
+ invite_accepted: never;
44
+ invite_declined: never;
45
+ invite_revoked: never;
46
+ role_changed: MemberRoleChangedMetadata;
47
+ removed: never;
48
+ };
49
+ team: {
50
+ updated: TeamUpdatedMetadata;
51
+ };
52
+ user: {
53
+ updated: UserUpdatedMetadata;
54
+ };
55
+ environment: {
56
+ created: EnvironmentCreatedMetadata;
57
+ updated: EnvironmentUpdatedMetadata;
58
+ variables_changed: EnvironmentVariablesChangedMetadata;
59
+ webhook_urls_changed: EnvironmentWebhookMetadata;
60
+ webhook_signing_key_rotated: never;
61
+ deleted: never;
62
+ };
63
+ app_auth: {
64
+ login: AppAuthLoginMetadata;
65
+ logout: never;
66
+ signup: never;
67
+ password_changed: never;
68
+ password_reset: never;
69
+ };
70
+ mfa: {
71
+ enrolled: never;
72
+ enabled: never;
73
+ disabled: never;
74
+ verified: MfaVerifiedMetadata;
75
+ recovery_regenerated: never;
76
+ };
77
+ billing: {
78
+ plan_changed: BillingPlanChangedMetadata;
79
+ trial_extended: never;
80
+ details_changed: never;
81
+ payment_method_added: never;
82
+ payment_method_removed: BillingPaymentMethodRemovedMetadata;
83
+ spend_alert_changed: BillingSpendAlertChangedMetadata;
84
+ spend_alert_removed: never;
85
+ };
86
+ audit_trail: {
87
+ exported: AuditTrailFiltersMetadata;
88
+ queried: AuditTrailQueriedMetadata;
89
+ };
18
90
  }
19
91
  export type AuditResource = keyof AuditEventTable;
20
- export type AuditActionOf<R extends AuditResource> = AuditEventTable[R];
92
+ export type AuditActionOf<R extends AuditResource> = R extends AuditResource ? keyof AuditEventTable[R] & string : never;
21
93
  export type AuditAction = AuditActionOf<AuditResource>;
22
94
  export type AuditEventKey = {
23
- [R in AuditResource]: `${R}.${AuditEventTable[R]}`;
95
+ [R in AuditResource]: `${R}.${AuditActionOf<R>}`;
24
96
  }[AuditResource];
97
+ /** The metadata an action may carry. `never` for the actions that carry none. */
98
+ export type AuditMetadataFor<R extends AuditResource, A> = A extends keyof AuditEventTable[R] ? AuditEventTable[R][A] : never;
25
99
  export type AuditScope = 'account' | 'environment';
26
100
  export type AuditTargetType = 'connection' | 'sync' | 'function' | 'integration' | 'api_key' | 'member' | 'team' | 'user' | 'environment';
27
101
  export interface AuditActor {
@@ -29,6 +103,12 @@ export interface AuditActor {
29
103
  id: string;
30
104
  display?: string;
31
105
  }
106
+ export interface AuditVia {
107
+ type: AuditViaType;
108
+ id: string;
109
+ display?: string;
110
+ actorId?: string;
111
+ }
32
112
  export interface AuditTarget {
33
113
  type: AuditTargetType;
34
114
  id: string;
@@ -39,6 +119,15 @@ export interface AuditContext {
39
119
  ip?: string;
40
120
  userAgent?: string;
41
121
  }
122
+ export interface AuditAttribution {
123
+ kind: 'request';
124
+ actor: AuditActor;
125
+ context: AuditContext;
126
+ }
127
+ export interface NoAttribution {
128
+ kind: 'no-attribution';
129
+ reason: string;
130
+ }
42
131
  export interface AuditPolicy<R extends AuditResource = AuditResource, A extends AuditActionOf<R> = AuditActionOf<R>, S extends AuditScope = AuditScope> {
43
132
  kind: 'audit';
44
133
  resource: R;
@@ -53,4 +142,35 @@ export type EndpointAudit = AuditPolicy | NoAudit<string>;
53
142
  export type SerializedAuditEvent = {
54
143
  event: string;
55
144
  };
145
+ export type AuditResourceAction = {
146
+ [R in AuditResource]: {
147
+ [A in AuditActionOf<R>]: [AuditMetadataFor<R, A>] extends [never] ? {
148
+ resource: R;
149
+ action: A;
150
+ } : {
151
+ resource: R;
152
+ action: A;
153
+ metadata?: AuditMetadataFor<R, A>;
154
+ };
155
+ }[AuditActionOf<R>];
156
+ }[AuditResource];
157
+ interface AuditEventCommon {
158
+ occurredAt: string;
159
+ accountId: number;
160
+ scope: AuditScope;
161
+ environment: {
162
+ id: string;
163
+ display: string;
164
+ } | null;
165
+ actor: AuditActor;
166
+ via?: AuditVia[];
167
+ targets: AuditTarget[];
168
+ context: AuditContext;
169
+ outcome: AuditOutcome;
170
+ }
171
+ export type AuditEvent = AuditEventCommon & AuditResourceAction;
172
+ export type StoredAuditEvent = AuditEvent & {
173
+ id: string;
174
+ version: AuditTrailVersion;
175
+ };
56
176
  export {};
@@ -0,0 +1,99 @@
1
+ import type { FunctionSource } from '../syncConfigs/db.js';
2
+ export interface ConnectionMetadata {
3
+ providerConfigKey?: string;
4
+ }
5
+ export interface ConnectionUpdatedMetadata {
6
+ providerConfigKey?: string;
7
+ changedFields?: string[];
8
+ }
9
+ export interface IntegrationProviderMetadata {
10
+ provider?: string;
11
+ }
12
+ export interface IntegrationUpdatedMetadata {
13
+ changedFields?: string[];
14
+ }
15
+ export interface EnvironmentCreatedMetadata {
16
+ name?: string;
17
+ }
18
+ export interface AuditTrailFiltersMetadata {
19
+ from?: string;
20
+ to?: string;
21
+ resources?: string[];
22
+ actions?: string[];
23
+ }
24
+ export interface AuditTrailQueriedMetadata extends AuditTrailFiltersMetadata {
25
+ continued?: boolean;
26
+ }
27
+ export interface MemberInvitedMetadata {
28
+ role?: string;
29
+ }
30
+ export interface FunctionDeployedMetadata {
31
+ source?: FunctionSource;
32
+ type?: string;
33
+ }
34
+ export interface FunctionUpgradedMetadata {
35
+ upgradeVersion?: string;
36
+ }
37
+ export interface FunctionDeletedMetadata {
38
+ type?: string;
39
+ }
40
+ export interface ApiKeyUpdatedMetadata {
41
+ displayName?: string;
42
+ scopes?: string[];
43
+ }
44
+ export interface SyncBaseMetadata {
45
+ providerConfigKey?: string;
46
+ connectionId?: string;
47
+ }
48
+ export interface SyncFrequencyChangedMetadata extends SyncBaseMetadata {
49
+ frequency?: string;
50
+ }
51
+ export interface SyncVariantMetadata extends SyncBaseMetadata {
52
+ variant?: string;
53
+ }
54
+ export interface SyncTriggeredMetadata extends SyncBaseMetadata {
55
+ reset?: boolean;
56
+ emptyCache?: boolean;
57
+ }
58
+ export interface MemberRoleChangedMetadata {
59
+ fromRole?: string;
60
+ toRole?: string;
61
+ }
62
+ export interface TeamUpdatedMetadata {
63
+ name?: string;
64
+ }
65
+ export interface UserUpdatedMetadata {
66
+ name?: string;
67
+ gettingStartedClosed?: boolean;
68
+ }
69
+ export interface EnvironmentUpdatedMetadata {
70
+ name?: string;
71
+ changedFields?: string[];
72
+ }
73
+ export interface EnvironmentVariablesChangedMetadata {
74
+ variableCount?: number;
75
+ variableNames?: string[];
76
+ }
77
+ export interface EnvironmentWebhookMetadata {
78
+ changedFields?: string[];
79
+ primaryUrl?: string;
80
+ secondaryUrl?: string;
81
+ }
82
+ export interface BillingPlanChangedMetadata {
83
+ fromPlan?: string;
84
+ toPlan?: string;
85
+ }
86
+ export type AppAuthLoginMethod = 'local' | 'sso' | 'managed';
87
+ export interface AppAuthLoginMetadata {
88
+ mfaRequired?: boolean;
89
+ method?: AppAuthLoginMethod;
90
+ }
91
+ export interface BillingPaymentMethodRemovedMetadata {
92
+ paymentMethodId?: string;
93
+ }
94
+ export interface MfaVerifiedMetadata {
95
+ method?: 'totp' | 'recovery_code';
96
+ }
97
+ export interface BillingSpendAlertChangedMetadata {
98
+ thresholdInCents?: number;
99
+ }
@@ -20,7 +20,7 @@ export interface AuthModes {
20
20
  AwsSigV4: 'AWS_SIGV4';
21
21
  }
22
22
  export type AuthModeType = AuthModes[keyof AuthModes];
23
- export type AuthOperationType = 'creation' | 'override' | 'refresh' | 'unknown';
23
+ export type AuthOperationType = 'creation' | 'override' | 'refresh' | 'deletion' | 'unknown';
24
24
  export interface OAuthAuthorizationMethod {
25
25
  BODY: 'body';
26
26
  HEADER: 'header';
@@ -1,4 +1,5 @@
1
1
  import type { ApiEndpoint, ApiError } from '../api.js';
2
+ import type { AuditPolicy } from '../audit-trail/event.js';
2
3
  export type ConnectionQueryString = {
3
4
  connection_id?: string | undefined;
4
5
  params?: Record<string, any> | undefined;
@@ -35,10 +36,7 @@ export interface WebSocketConnectionResponseSuccess {
35
36
  }
36
37
  type AuthErrors = ApiError<'invalid_body'> | ApiError<'invalid_query_params'> | ApiError<'unknown_provider_config'> | ApiError<'unknown_provider_template'> | ApiError<'invalid_auth_mode'> | ApiError<'invalid_credentials'> | ApiError<'integration_not_allowed'> | ApiError<'invalid_connection'> | ApiError<'connection_test_failed'> | ApiError<'connection_validation_failed'>;
37
38
  export type PostPublicApiKeyAuthorization = ApiEndpoint<{
38
- Audit: {
39
- kind: 'no-audit';
40
- reason: 'TODO: audit coverage pending';
41
- };
39
+ Audit: AuditPolicy<'connection', 'created', 'environment'>;
42
40
  Method: 'POST';
43
41
  Body: {
44
42
  apiKey: string;
@@ -52,10 +50,7 @@ export type PostPublicApiKeyAuthorization = ApiEndpoint<{
52
50
  Success: ConnectionResponseSuccess;
53
51
  }>;
54
52
  export type PostPublicBasicAuthorization = ApiEndpoint<{
55
- Audit: {
56
- kind: 'no-audit';
57
- reason: 'TODO: audit coverage pending';
58
- };
53
+ Audit: AuditPolicy<'connection', 'created', 'environment'>;
59
54
  Method: 'POST';
60
55
  Body: {
61
56
  username: string;
@@ -70,10 +65,7 @@ export type PostPublicBasicAuthorization = ApiEndpoint<{
70
65
  Success: ConnectionResponseSuccess;
71
66
  }>;
72
67
  export type PostPublicTbaAuthorization = ApiEndpoint<{
73
- Audit: {
74
- kind: 'no-audit';
75
- reason: 'TODO: audit coverage pending';
76
- };
68
+ Audit: AuditPolicy<'connection', 'created', 'environment'>;
77
69
  Method: 'POST';
78
70
  Body: {
79
71
  token_id: string;
@@ -91,10 +83,7 @@ export type PostPublicTbaAuthorization = ApiEndpoint<{
91
83
  Success: ConnectionResponseSuccess;
92
84
  }>;
93
85
  export type PostPublicJwtAuthorization = ApiEndpoint<{
94
- Audit: {
95
- kind: 'no-audit';
96
- reason: 'TODO: audit coverage pending';
97
- };
86
+ Audit: AuditPolicy<'connection', 'created', 'environment'>;
98
87
  Method: 'POST';
99
88
  Body: Record<string, any>;
100
89
  Querystring: ConnectionQueryString;
@@ -106,10 +95,7 @@ export type PostPublicJwtAuthorization = ApiEndpoint<{
106
95
  Success: ConnectionResponseSuccess;
107
96
  }>;
108
97
  export type PostPublicUnauthenticatedAuthorization = ApiEndpoint<{
109
- Audit: {
110
- kind: 'no-audit';
111
- reason: 'TODO: audit coverage pending';
112
- };
98
+ Audit: AuditPolicy<'connection', 'created', 'environment'>;
113
99
  Method: 'POST';
114
100
  Querystring: ConnectionQueryString;
115
101
  Params: {
@@ -120,10 +106,7 @@ export type PostPublicUnauthenticatedAuthorization = ApiEndpoint<{
120
106
  Success: ConnectionResponseSuccess;
121
107
  }>;
122
108
  export type PostPublicBillAuthorization = ApiEndpoint<{
123
- Audit: {
124
- kind: 'no-audit';
125
- reason: 'TODO: audit coverage pending';
126
- };
109
+ Audit: AuditPolicy<'connection', 'created', 'environment'>;
127
110
  Method: 'POST';
128
111
  Body: {
129
112
  username: string;
@@ -140,10 +123,7 @@ export type PostPublicBillAuthorization = ApiEndpoint<{
140
123
  Success: ConnectionResponseSuccess;
141
124
  }>;
142
125
  export type PostPublicTwoStepAuthorization = ApiEndpoint<{
143
- Audit: {
144
- kind: 'no-audit';
145
- reason: 'TODO: audit coverage pending';
146
- };
126
+ Audit: AuditPolicy<'connection', 'created', 'environment'>;
147
127
  Method: 'POST';
148
128
  Body: Record<string, any>;
149
129
  Querystring: ConnectionQueryString;
@@ -155,10 +135,7 @@ export type PostPublicTwoStepAuthorization = ApiEndpoint<{
155
135
  Success: ConnectionResponseSuccess;
156
136
  }>;
157
137
  export type PostPublicSignatureAuthorization = ApiEndpoint<{
158
- Audit: {
159
- kind: 'no-audit';
160
- reason: 'TODO: audit coverage pending';
161
- };
138
+ Audit: AuditPolicy<'connection', 'created', 'environment'>;
162
139
  Method: 'POST';
163
140
  Body: {
164
141
  username: string;
@@ -174,10 +151,7 @@ export type PostPublicSignatureAuthorization = ApiEndpoint<{
174
151
  }>;
175
152
  type AwsSigV4AuthErrors = AuthErrors | ApiError<'invalid_aws_sigv4_config'> | ApiError<'missing_aws_sigv4_service'> | ApiError<'missing_aws_sigv4_sts_endpoint'> | ApiError<'missing_aws_sigv4_builtin_credentials'> | ApiError<'missing_aws_sigv4_region'> | ApiError<'aws_sigv4_sts_request_failed'>;
176
153
  export type PostPublicAwsSigV4Authorization = ApiEndpoint<{
177
- Audit: {
178
- kind: 'no-audit';
179
- reason: 'TODO: audit coverage pending';
180
- };
154
+ Audit: AuditPolicy<'connection', 'created', 'environment'>;
181
155
  Method: 'POST';
182
156
  Body: {
183
157
  role_arn: string;
@@ -192,10 +166,7 @@ export type PostPublicAwsSigV4Authorization = ApiEndpoint<{
192
166
  Success: ConnectionResponseSuccess;
193
167
  }>;
194
168
  export type PostPublicOauthOutboundAuthorization = ApiEndpoint<{
195
- Audit: {
196
- kind: 'no-audit';
197
- reason: 'TODO: audit coverage pending';
198
- };
169
+ Audit: AuditPolicy<'connection', 'created', 'environment'>;
199
170
  Method: 'POST';
200
171
  Body: {
201
172
  username: string;
@@ -1,6 +1,6 @@
1
1
  import type { Role } from '../user/db.js';
2
2
  export type Action = 'create' | 'read' | 'update' | 'delete' | '*';
3
- export type Resource = 'team' | 'team_member' | 'invite' | 'connect_ui_settings' | 'billing' | 'plan' | 'environment' | 'environment_production_flag' | 'environment_key' | 'environment_variable' | 'webhook' | 'integration' | 'connection' | 'flow' | 'sync_command' | 'secret_key' | 'connection_credential' | 'log' | 'audit_trail' | '*';
3
+ export type Resource = 'team' | 'team_member' | 'invite' | 'connect_ui_settings' | 'billing' | 'plan' | 'environment' | 'environment_production_flag' | 'environment_key' | 'account_key' | 'environment_variable' | 'webhook' | 'integration' | 'connection' | 'flow' | 'sync_command' | 'secret_key' | 'connection_credential' | 'log' | 'audit_trail' | '*';
4
4
  export type Scope = 'production' | 'non-production' | 'global';
5
5
  export interface Permission {
6
6
  action: Action;
@@ -8,6 +8,14 @@ export interface BillingClient {
8
8
  getCustomer: (accountId: number) => Promise<Result<BillingCustomer>>;
9
9
  putCustomer: (accountId: number, invoicingDetails: BillingInvoicingDetails) => Promise<Result<BillingCustomer>>;
10
10
  getSubscription: (accountId: number) => Promise<Result<BillingSubscription | null>>;
11
+ getOverdueInvoices: (accountId: number) => Promise<Result<BillingOverdueInvoices>>;
12
+ getUpcomingInvoice: (subscriptionId: string) => Promise<Result<BillingUpcomingInvoice | null>>;
13
+ getPeriodCosts: (subscriptionId: string) => Promise<Result<BillingPeriodCosts | null>>;
14
+ getSpendAlert: (subscriptionId: string) => Promise<Result<BillingSpendAlert | null>>;
15
+ setSpendAlert: (subscriptionId: string, opts: {
16
+ thresholdInCents: number;
17
+ }) => Promise<Result<BillingSpendAlert>>;
18
+ removeSpendAlert: (subscriptionId: string) => Promise<Result<void>>;
11
19
  createSubscription: (team: DBTeam, planExternalId: string) => Promise<Result<BillingSubscription>>;
12
20
  getUsage: (subscriptionId: string, opts?: GetBillingUsageOpts) => Promise<Result<BillingUsageMetrics>>;
13
21
  upgrade: (opts: {
@@ -24,16 +32,16 @@ export interface BillingClient {
24
32
  applyPendingChanges: (opts: {
25
33
  pendingChangeId: string;
26
34
  /**
27
- * Stripe PaymentIntent ID, used to cross-reference the payment in Orb.
35
+ * Payment collected up front.
36
+ *
37
+ * Omitted for a plan billed fully in arrears, where nothing is collected when the change is applied.
28
38
  */
29
- paymentExternalId: string;
30
- /**
31
- * Amount collected via Stripe in dollars (e.g. "25.00"). Orb uses this
32
- * to credit the customer the difference vs. the actual invoice amount,
33
- * so overcharges (e.g. when falling back to the base fee) are corrected
34
- * automatically. No credit is issued if the amounts match exactly.
35
- */
36
- amountCollected: string;
39
+ payment?: {
40
+ /** The external payment ID; for Stripe, it's the PaymentIntent ID. */
41
+ externalId: string;
42
+ /** Amount collected in dollars. */
43
+ amountCollected: string;
44
+ } | undefined;
37
45
  }) => Promise<Result<BillingSubscription>>;
38
46
  cancelPendingChanges: (opts: {
39
47
  pendingChangeId: string;
@@ -49,6 +57,7 @@ export interface BillingCustomer {
49
57
  export interface BillingInvoicingDetails {
50
58
  legalEntityName: string;
51
59
  email: string;
60
+ additionalEmails: string[];
52
61
  address: BillingAddress | null;
53
62
  taxId: BillingTaxId | null;
54
63
  }
@@ -70,6 +79,42 @@ export interface BillingSubscription {
70
79
  pendingChangeId?: string | undefined;
71
80
  planExternalId: string;
72
81
  }
82
+ export interface BillingOverdueInvoices {
83
+ hasOverdue: boolean;
84
+ }
85
+ /** Orb's upcoming invoice for a subscription — the whole invoice, not a month's slice of it. */
86
+ export interface BillingUpcomingInvoice {
87
+ amountInCents: number;
88
+ /** ISO 4217, uppercased. Orb's `credits` is rejected upstream. */
89
+ currency: string;
90
+ }
91
+ /** Orb's single `cost_exceeded` alert for a subscription; Orb holds all of its state. */
92
+ export interface BillingSpendAlert {
93
+ id: string;
94
+ thresholdInCents: number;
95
+ /** ISO 4217, uppercased. Null when Orb reports a unit that isn't a currency. */
96
+ currency: string | null;
97
+ }
98
+ export interface BillingPeriodCosts {
99
+ /** Integer cents charged this billing period per metric, excluding every fixed price. A metric is
100
+ * absent when the subscription carries no price for it, which is not the same as being charged 0. */
101
+ metrics: Partial<Record<UsageMetric, number>>;
102
+ /** Metrics with a real price whose charge we couldn't read — an unparseable amount, or a currency
103
+ * other prices don't share. A charge exists; we just can't state it, so it reads as a dash, not $0. */
104
+ malformedMetrics: UsageMetric[];
105
+ /** False when a price maps to no metric of ours, so an unpriced row can't safely claim $0 — the
106
+ * money might be one of theirs. */
107
+ fullyAttributed: boolean;
108
+ /** The individual prices behind `malformedMetrics` and a false `fullyAttributed`, for alerting —
109
+ * not sent over HTTP. */
110
+ flagged: {
111
+ priceId: string;
112
+ priceName: string;
113
+ metric: UsageMetric | null;
114
+ amountInCents: number | null;
115
+ }[];
116
+ currency: string;
117
+ }
73
118
  export type CounterUsageMetric = Exclude<UsageMetric, 'records' | 'connections'>;
74
119
  export type AvgUsageMetric = Extract<UsageMetric, 'records' | 'connections'>;
75
120
  export interface BreakdownDimensions {
@@ -77,10 +122,11 @@ export interface BreakdownDimensions {
77
122
  function_executions: 'environment_id' | 'integration_id' | 'connection_id' | 'function_name' | 'function_type' | 'success';
78
123
  function_logs: 'environment_id' | 'integration_id' | 'connection_id' | 'function_name' | 'function_type' | 'success';
79
124
  function_compute_gbms: 'environment_id' | 'integration_id' | 'connection_id' | 'function_name' | 'function_type' | 'success';
125
+ function_duration_seconds: 'environment_id' | 'integration_id' | 'connection_id' | 'function_name' | 'function_type' | 'success';
80
126
  webhook_forwards: 'environment_id' | 'integration_id' | 'connection_id' | 'success';
81
127
  records: 'environment_id' | 'integration_id' | 'connection_id' | 'model';
82
128
  connections: 'environment_id' | 'integration_id';
83
- data_transfer: 'environment_id' | 'integration_id' | 'connection_id' | 'package' | 'callsite';
129
+ data_transfer: 'environment_id' | 'integration_id' | 'connection_id' | 'source';
84
130
  }
85
131
  export type DimensionFor<M extends UsageMetric> = 'none' | BreakdownDimensions[M];
86
132
  export interface GetBillingUsageOpts {
@@ -171,7 +171,7 @@ export type GetPublicConnection = ApiEndpoint<{
171
171
  refresh_github_app_jwt_token?: boolean | undefined;
172
172
  };
173
173
  Path: '/connection/:connectionId';
174
- Error: ApiError<'unknown_provider_config' | 'invalid_credentials'>;
174
+ Error: ApiError<'unknown_provider_config' | 'not_found' | 'invalid_credentials' | 'server_error'>;
175
175
  Success: ApiPublicConnectionFull;
176
176
  }>;
177
177
  export type PatchPublicConnection = ApiEndpoint<{
@@ -8,7 +8,10 @@ export interface MetadataBody {
8
8
  }
9
9
  type MetadataError = ApiError<'invalid_body'> | ApiError<'unknown_connection'>;
10
10
  export type SetMetadata = ApiEndpoint<{
11
- Audit: AuditPolicy<'connection', 'metadata_updated', 'environment'>;
11
+ Audit: {
12
+ kind: 'no-audit';
13
+ reason: 'data-plane operation';
14
+ };
12
15
  Method: 'POST';
13
16
  Body: MetadataBody;
14
17
  Path: '/connection/metadata';
@@ -16,7 +19,10 @@ export type SetMetadata = ApiEndpoint<{
16
19
  Success: MetadataBody;
17
20
  }>;
18
21
  export type UpdateMetadata = ApiEndpoint<{
19
- Audit: AuditPolicy<'connection', 'metadata_updated', 'environment'>;
22
+ Audit: {
23
+ kind: 'no-audit';
24
+ reason: 'data-plane operation';
25
+ };
20
26
  Method: 'PATCH';
21
27
  Path: '/connection/metadata';
22
28
  Body: MetadataBody;