@stripe/extensibility-custom-objects 0.7.4

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 (48) hide show
  1. package/LICENSE.md +19 -0
  2. package/README.md +63 -0
  3. package/dist/decorators/action.d.ts +29 -0
  4. package/dist/decorators/action.d.ts.map +1 -0
  5. package/dist/decorators/custom-fields.d.ts +16 -0
  6. package/dist/decorators/custom-fields.d.ts.map +1 -0
  7. package/dist/decorators/custom-object.d.ts +19 -0
  8. package/dist/decorators/custom-object.d.ts.map +1 -0
  9. package/dist/decorators/index.d.ts +14 -0
  10. package/dist/decorators/index.d.ts.map +1 -0
  11. package/dist/extensibility-custom-objects-alpha.d.ts +245 -0
  12. package/dist/extensibility-custom-objects-beta.d.ts +245 -0
  13. package/dist/extensibility-custom-objects-internal.d.ts +680 -0
  14. package/dist/extensibility-custom-objects-public.d.ts +245 -0
  15. package/dist/index.cjs +761 -0
  16. package/dist/index.d.ts +26 -0
  17. package/dist/index.d.ts.map +1 -0
  18. package/dist/index.js +710 -0
  19. package/dist/runtime/base-object.d.ts +84 -0
  20. package/dist/runtime/base-object.d.ts.map +1 -0
  21. package/dist/runtime/deep-clone.d.ts +16 -0
  22. package/dist/runtime/deep-clone.d.ts.map +1 -0
  23. package/dist/runtime/events.d.ts +161 -0
  24. package/dist/runtime/events.d.ts.map +1 -0
  25. package/dist/runtime/flush-helpers.d.ts +9 -0
  26. package/dist/runtime/flush-helpers.d.ts.map +1 -0
  27. package/dist/runtime/invoke.d.ts +19 -0
  28. package/dist/runtime/invoke.d.ts.map +1 -0
  29. package/dist/runtime/persist.d.ts +44 -0
  30. package/dist/runtime/persist.d.ts.map +1 -0
  31. package/dist/runtime/proxy/constants.d.ts +5 -0
  32. package/dist/runtime/proxy/constants.d.ts.map +1 -0
  33. package/dist/runtime/proxy/fields-proxy.d.ts +19 -0
  34. package/dist/runtime/proxy/fields-proxy.d.ts.map +1 -0
  35. package/dist/runtime/proxy/index.d.ts +5 -0
  36. package/dist/runtime/proxy/index.d.ts.map +1 -0
  37. package/dist/runtime/proxy/instance-proxy.d.ts +81 -0
  38. package/dist/runtime/proxy/instance-proxy.d.ts.map +1 -0
  39. package/dist/runtime/proxy/types.d.ts +25 -0
  40. package/dist/runtime/proxy/types.d.ts.map +1 -0
  41. package/dist/runtime/registry.d.ts +40 -0
  42. package/dist/runtime/registry.d.ts.map +1 -0
  43. package/dist/runtime/symbol-helpers.d.ts +17 -0
  44. package/dist/runtime/symbol-helpers.d.ts.map +1 -0
  45. package/dist/runtime/types.d.ts +139 -0
  46. package/dist/runtime/types.d.ts.map +1 -0
  47. package/dist/tsconfig.build.tsbuildinfo +1 -0
  48. package/package.json +48 -0
package/LICENSE.md ADDED
@@ -0,0 +1,19 @@
1
+ Copyright (C) 2026 Stripe, Inc. (https://stripe.com)
2
+
3
+ Permission is hereby granted, free of charge, to any person obtaining a copy
4
+ of this software and associated documentation files (the "Software"), to deal
5
+ in the Software without restriction, including without limitation the rights
6
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
7
+ copies of the Software, and to permit persons to whom the Software is
8
+ furnished to do so, subject to the following conditions:
9
+
10
+ The above copyright notice and this permission notice shall be included in
11
+ all copies or substantial portions of the Software.
12
+
13
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
18
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
19
+ THE SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,63 @@
1
+ # @stripe/extensibility-custom-objects
2
+
3
+ TypeScript decorators and runtime for defining Stripe custom objects.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ npm install @stripe/extensibility-custom-objects
9
+ npm install --save-dev @stripe/extensibility-custom-objects-tools
10
+ ```
11
+
12
+ ## Quick Start
13
+
14
+ Define a custom object using the two-class pattern — a fields class for data and
15
+ an outer class for behavior:
16
+
17
+ ```typescript
18
+ import { CustomObject, CustomFields, Action } from '@stripe/extensibility-custom-objects';
19
+ import { Field } from '@stripe/extensibility-jsonschema';
20
+
21
+ @CustomFields
22
+ export class ShipmentFields {
23
+ /** @primaryField @displayName Tracking Number */
24
+ trackingNumber!: string;
25
+
26
+ /** @secondaryField @displayName Delivered */
27
+ delivered!: boolean;
28
+
29
+ /** @displayName Weight (lbs) */
30
+ weightInLbs: number = 0;
31
+ }
32
+
33
+ /**
34
+ * @apiName shipment
35
+ * @displayName Shipment
36
+ */
37
+ @CustomObject
38
+ export class Shipment extends BaseObject<ShipmentFields> {
39
+ /**
40
+ * @apiName mark_delivered
41
+ * @displayName Mark Delivered
42
+ */
43
+ @Action
44
+ async markDelivered(): Promise<void> {
45
+ this.data.delivered = true;
46
+ await this.save();
47
+ }
48
+
49
+ /** @apiName export_manifest */
50
+ @Action
51
+ async exportManifest(): Promise<string> {
52
+ return `${this.data.trackingNumber}: ${this.data.weightInLbs}lbs`;
53
+ }
54
+ }
55
+ ```
56
+
57
+ Build your code:
58
+
59
+ ```bash
60
+ custom-objects-build --input src --output dist
61
+ ```
62
+
63
+ See [Custom Object DSL Reference](../../docs/custom-object-dsl.md) for full documentation.
@@ -0,0 +1,29 @@
1
+ /**
2
+ * Context type that restricts decorator application to instance methods only.
3
+ * Uses `{ readonly static: false }` to make TypeScript reject `@Action` on static methods.
4
+ *
5
+ * @public
6
+ */
7
+ export type InstanceMethodDecoratorContext = { readonly static: false } & ClassMethodDecoratorContext;
8
+ /**
9
+ * Marks an instance method as an action on a custom object.
10
+ *
11
+ * This decorator is **inert at runtime** — it does not modify the method in any way.
12
+ * It serves as a marker for the build-time transformer, which extracts action metadata
13
+ * and generates the necessary platform registration code.
14
+ *
15
+ * Can only be applied to instance methods, not static methods. Applying `@Action`
16
+ * to a static method is a TypeScript compile error.
17
+ *
18
+ * All naming metadata is expressed via TSDoc annotation tags in a JSDoc comment
19
+ * on the method: `@apiName`, `@displayName`, `@description`.
20
+ *
21
+ * @example
22
+ * Use TSDoc tags in a JSDoc comment above the decorator,
23
+ * e.g. `@apiName mark_delivered` and `@displayName Mark Delivered`,
24
+ * then apply the bare decorator `@Action`.
25
+ *
26
+ * @public
27
+ */
28
+ export declare function Action(_target: (...args: never) => unknown, _context: InstanceMethodDecoratorContext): void;
29
+ //# sourceMappingURL=action.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"action.d.ts","sourceRoot":"","sources":["../../src/decorators/action.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,8BAA8B,GAAG,2BAA2B,GAAG;IACzE,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC;CACxB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,MAAM,CACpB,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,EACpC,QAAQ,EAAE,8BAA8B,GACvC,IAAI,CAEN"}
@@ -0,0 +1,16 @@
1
+ /**
2
+ * Marks a class as a custom fields container for a custom object.
3
+ *
4
+ * This decorator is **inert at runtime** — it does not modify the class in any way.
5
+ * It serves as a marker for the build-time transformer, which discovers the fields
6
+ * class by this decorator and extracts field metadata from its members.
7
+ *
8
+ * The fields class must contain only field declarations (no methods). Use
9
+ * TSDoc tags from `@stripe/extensibility-jsonschema` on each field to control
10
+ * display and validation. Exactly one field should be tagged `primaryField`
11
+ * and at most one `secondaryField`.
12
+ *
13
+ * @public
14
+ */
15
+ export declare function CustomFields(_target: new (...args: unknown[]) => unknown, _context: ClassDecoratorContext): void;
16
+ //# sourceMappingURL=custom-fields.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"custom-fields.d.ts","sourceRoot":"","sources":["../../src/decorators/custom-fields.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,QAAQ,MAAM,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,EACrD,QAAQ,EAAE,qBAAqB,GAC9B,IAAI,CAEN"}
@@ -0,0 +1,19 @@
1
+ /**
2
+ * Marks a class as a custom object type.
3
+ *
4
+ * This decorator is **inert at runtime** — it does not modify the class in any way.
5
+ * It serves as a marker for the build-time transformer, which extracts metadata
6
+ * and generates the necessary platform registration code.
7
+ *
8
+ * All naming metadata is expressed via TSDoc annotation tags in a JSDoc comment
9
+ * on the class: `@apiName`, `@displayName`, `@description`.
10
+ *
11
+ * @example
12
+ * Use TSDoc tags in a JSDoc comment above the decorator,
13
+ * e.g. `@apiName installment_plan` and `@displayName Installment plan`,
14
+ * then apply the bare decorator `@CustomObject`.
15
+ *
16
+ * @public
17
+ */
18
+ export declare function CustomObject(_target: new (...args: unknown[]) => unknown, _context: ClassDecoratorContext): void;
19
+ //# sourceMappingURL=custom-object.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"custom-object.d.ts","sourceRoot":"","sources":["../../src/decorators/custom-object.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,QAAQ,MAAM,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,EACrD,QAAQ,EAAE,qBAAqB,GAC9B,IAAI,CAEN"}
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Decorator types and functions for marking custom object classes and actions.
3
+ *
4
+ * All decorators in this module are **inert at runtime** — they serve as markers
5
+ * for the build-time transformer to extract metadata and generate platform
6
+ * registration code.
7
+ *
8
+ * @internal
9
+ */
10
+ export { CustomObject } from './custom-object.js';
11
+ export { CustomFields } from './custom-fields.js';
12
+ export { Action } from './action.js';
13
+ export type { InstanceMethodDecoratorContext } from './action.js';
14
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/decorators/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EAAE,8BAA8B,EAAE,MAAM,aAAa,CAAC"}
@@ -0,0 +1,245 @@
1
+ /**
2
+ * Stripe Custom Objects SDK
3
+ *
4
+ * Provides decorators and runtime support for defining custom object types
5
+ * that integrate with the Stripe platform. Custom objects are defined using
6
+ * TypeScript classes with decorators, then transformed at build time using
7
+ * `@stripe/extensibility-custom-objects-tools`.
8
+ *
9
+ * @packageDocumentation
10
+ */
11
+
12
+ /* Excluded from this release type: __hasPendingChanges */
13
+
14
+ /* Excluded from this release type: __queueSave */
15
+
16
+ /**
17
+ * Marks an instance method as an action on a custom object.
18
+ *
19
+ * This decorator is **inert at runtime** — it does not modify the method in any way.
20
+ * It serves as a marker for the build-time transformer, which extracts action metadata
21
+ * and generates the necessary platform registration code.
22
+ *
23
+ * Can only be applied to instance methods, not static methods. Applying `@Action`
24
+ * to a static method is a TypeScript compile error.
25
+ *
26
+ * All naming metadata is expressed via TSDoc annotation tags in a JSDoc comment
27
+ * on the method: `@apiName`, `@displayName`, `@description`.
28
+ *
29
+ * @example
30
+ * Use TSDoc tags in a JSDoc comment above the decorator,
31
+ * e.g. `@apiName mark_delivered` and `@displayName Mark Delivered`,
32
+ * then apply the bare decorator `@Action`.
33
+ *
34
+ * @public
35
+ */
36
+ export declare function Action(_target: (...args: never) => unknown, _context: InstanceMethodDecoratorContext): void;
37
+
38
+ /* Excluded from this release type: _ActionMetadata */
39
+
40
+ /* Excluded from this release type: _assemblePayload */
41
+
42
+ /**
43
+ * Abstract base class for all custom objects.
44
+ *
45
+ * Provides built-in platform fields (id, object, created, updated, livemode)
46
+ * and a typed `fields` container for user-defined fields. The generic parameter
47
+ * `T` describes the shape of user fields accessible via `this.fields`.
48
+ *
49
+ * @remarks
50
+ * **Definite assignment assertions (`!`)**: All platform fields (`id`, `object`,
51
+ * `created`, `updated`, `livemode`, `fields`) use the TypeScript definite assignment
52
+ * assertion operator. This suppresses the "property has no initializer" error because
53
+ * these fields are intentionally left unset by the zero-argument constructor.
54
+ *
55
+ * The runtime (`executeInstanceMethod` in `invoke.ts`) is solely responsible for
56
+ * populating these fields via `Object.assign` and `hydrateInstance` **before** the
57
+ * dirty-tracking proxy is installed. Code that constructs a subclass directly
58
+ * (bypassing the runtime) will have `undefined` values for all platform fields at
59
+ * runtime, despite the types suggesting otherwise.
60
+ *
61
+ * @typeParam T - Shape of user-defined fields stored in `fields`
62
+ * @public
63
+ */
64
+ export declare abstract class BaseObject<T extends Record<string, unknown> = Record<string, unknown>> {
65
+ /** Unique identifier assigned by the platform */
66
+ readonly id: string;
67
+ /** Object type identifier assigned by the platform */
68
+ readonly object: string;
69
+ /** Timestamp when the object was created */
70
+ readonly created: Date;
71
+ /** Timestamp when the object was last updated */
72
+ readonly updated: Date;
73
+ /** Whether the object exists in live mode (true) or test mode (false). @public */
74
+ readonly livemode: boolean;
75
+ /**
76
+ * User-defined fields container. Populated during hydration via Object.assign
77
+ * before the dirty-tracking proxy is installed.
78
+ * Access individual fields as `this.fields.fieldName`.
79
+ *
80
+ * @remarks
81
+ * The generic type `T` describes the shape of available fields after
82
+ * hydration, not at construction time. Fields may be undefined before
83
+ * the instance is hydrated with data from the platform.
84
+ *
85
+ * @public
86
+ */
87
+ readonly fields: T;
88
+ /**
89
+ * Flushes pending field mutations into the slated-updates accumulator.
90
+ *
91
+ * When called from a transformed action (no save handler configured), this
92
+ * records which fields were mutated so that the Logic wrapper can include them
93
+ * in the response envelope's `updatedFields`. No network call is made.
94
+ *
95
+ * When a save handler is configured (runtime invoke path), the handler is
96
+ * called for actual persistence and its result is returned.
97
+ *
98
+ * @returns The save result including `updatedFieldCount` (unique fields flushed)
99
+ * @throws Error if the object is not proxied
100
+ * @public
101
+ */
102
+ save(): Promise<SaveResult>;
103
+ /**
104
+ * Discard all pending changes and restore field values to their
105
+ * last-saved state. Has no effect if the object is not proxied.
106
+ *
107
+ * @public
108
+ */
109
+ revert(): void;
110
+ }
111
+
112
+ /* Excluded from this release type: _buildMethodResponse */
113
+
114
+ /* Excluded from this release type: _clearRegistry */
115
+
116
+ /* Excluded from this release type: _clearSlatedUpdates */
117
+
118
+ /* Excluded from this release type: _commitProxyState */
119
+
120
+ /* Excluded from this release type: _createEventEmitter */
121
+
122
+ /* Excluded from this release type: _createInstanceProxy */
123
+
124
+ /* Excluded from this release type: _CreateProxyOptions */
125
+
126
+ /**
127
+ * Marks a class as a custom fields container for a custom object.
128
+ *
129
+ * This decorator is **inert at runtime** — it does not modify the class in any way.
130
+ * It serves as a marker for the build-time transformer, which discovers the fields
131
+ * class by this decorator and extracts field metadata from its members.
132
+ *
133
+ * The fields class must contain only field declarations (no methods). Use
134
+ * TSDoc tags from `@stripe/extensibility-jsonschema` on each field to control
135
+ * display and validation. Exactly one field should be tagged `primaryField`
136
+ * and at most one `secondaryField`.
137
+ *
138
+ * @public
139
+ */
140
+ export declare function CustomFields(_target: new (...args: unknown[]) => unknown, _context: ClassDecoratorContext): void;
141
+
142
+ /**
143
+ * Marks a class as a custom object type.
144
+ *
145
+ * This decorator is **inert at runtime** — it does not modify the class in any way.
146
+ * It serves as a marker for the build-time transformer, which extracts metadata
147
+ * and generates the necessary platform registration code.
148
+ *
149
+ * All naming metadata is expressed via TSDoc annotation tags in a JSDoc comment
150
+ * on the class: `@apiName`, `@displayName`, `@description`.
151
+ *
152
+ * @example
153
+ * Use TSDoc tags in a JSDoc comment above the decorator,
154
+ * e.g. `@apiName installment_plan` and `@displayName Installment plan`,
155
+ * then apply the bare decorator `@CustomObject`.
156
+ *
157
+ * @public
158
+ */
159
+ export declare function CustomObject(_target: new (...args: unknown[]) => unknown, _context: ClassDecoratorContext): void;
160
+
161
+ /* Excluded from this release type: _CustomObjectConstructor */
162
+
163
+ /* Excluded from this release type: _executeMethod */
164
+
165
+ /* Excluded from this release type: _ExecuteMethodOptions */
166
+
167
+ /* Excluded from this release type: _ExecuteMethodRequest */
168
+
169
+ /* Excluded from this release type: _getProxyState */
170
+
171
+ /* Excluded from this release type: _getRegisteredApiNames */
172
+
173
+ /* Excluded from this release type: _getRegisteredClass */
174
+
175
+ /* Excluded from this release type: _getSlatedUpdates */
176
+
177
+ /* Excluded from this release type: _hasProxyState */
178
+
179
+ /* Excluded from this release type: _INSTANCE_CONTEXT */
180
+
181
+ /* Excluded from this release type: _InstanceContext */
182
+
183
+ /**
184
+ * Context type that restricts decorator application to instance methods only.
185
+ * Uses `{ readonly static: false }` to make TypeScript reject `@Action` on static methods.
186
+ *
187
+ * @public
188
+ */
189
+ export declare type InstanceMethodDecoratorContext = { readonly static: false } & ClassMethodDecoratorContext;
190
+
191
+ /* Excluded from this release type: _InvokeBeginEvent */
192
+
193
+ /* Excluded from this release type: _InvokeCompleteEvent */
194
+
195
+ /* Excluded from this release type: _InvokeErrorEvent */
196
+
197
+ /* Excluded from this release type: _isTrackedField */
198
+
199
+ /* Excluded from this release type: _persistObject */
200
+
201
+ /* Excluded from this release type: _PersistOptions */
202
+
203
+ /* Excluded from this release type: _PlatformMetadata */
204
+
205
+ /* Excluded from this release type: _ProxiedObject */
206
+
207
+ /* Excluded from this release type: _PROXY_STATE */
208
+
209
+ /* Excluded from this release type: _ProxySetEvent */
210
+
211
+ /* Excluded from this release type: _ProxyState */
212
+
213
+ /* Excluded from this release type: _registerClass */
214
+
215
+ /* Excluded from this release type: _RuntimeEvent */
216
+
217
+ /* Excluded from this release type: _RuntimeEventEmitter */
218
+
219
+ /* Excluded from this release type: _SaveBeginEvent */
220
+
221
+ /* Excluded from this release type: _SaveCompleteEvent */
222
+
223
+ /* Excluded from this release type: _SaveHandler */
224
+
225
+ /**
226
+ * Result returned from save operations.
227
+ *
228
+ * @public
229
+ */
230
+ export declare interface SaveResult {
231
+ /** Number of fields updated */
232
+ updatedFieldCount: number;
233
+ }
234
+
235
+ /* Excluded from this release type: _SpanBeginEvent */
236
+
237
+ /* Excluded from this release type: _SpanEndEvent */
238
+
239
+ /* Excluded from this release type: _SpanErrorEvent */
240
+
241
+ /* Excluded from this release type: _UNTRACKED_FIELDS */
242
+
243
+ /* Excluded from this release type: _UpdateFrame */
244
+
245
+ export { }
@@ -0,0 +1,245 @@
1
+ /**
2
+ * Stripe Custom Objects SDK
3
+ *
4
+ * Provides decorators and runtime support for defining custom object types
5
+ * that integrate with the Stripe platform. Custom objects are defined using
6
+ * TypeScript classes with decorators, then transformed at build time using
7
+ * `@stripe/extensibility-custom-objects-tools`.
8
+ *
9
+ * @packageDocumentation
10
+ */
11
+
12
+ /* Excluded from this release type: __hasPendingChanges */
13
+
14
+ /* Excluded from this release type: __queueSave */
15
+
16
+ /**
17
+ * Marks an instance method as an action on a custom object.
18
+ *
19
+ * This decorator is **inert at runtime** — it does not modify the method in any way.
20
+ * It serves as a marker for the build-time transformer, which extracts action metadata
21
+ * and generates the necessary platform registration code.
22
+ *
23
+ * Can only be applied to instance methods, not static methods. Applying `@Action`
24
+ * to a static method is a TypeScript compile error.
25
+ *
26
+ * All naming metadata is expressed via TSDoc annotation tags in a JSDoc comment
27
+ * on the method: `@apiName`, `@displayName`, `@description`.
28
+ *
29
+ * @example
30
+ * Use TSDoc tags in a JSDoc comment above the decorator,
31
+ * e.g. `@apiName mark_delivered` and `@displayName Mark Delivered`,
32
+ * then apply the bare decorator `@Action`.
33
+ *
34
+ * @public
35
+ */
36
+ export declare function Action(_target: (...args: never) => unknown, _context: InstanceMethodDecoratorContext): void;
37
+
38
+ /* Excluded from this release type: _ActionMetadata */
39
+
40
+ /* Excluded from this release type: _assemblePayload */
41
+
42
+ /**
43
+ * Abstract base class for all custom objects.
44
+ *
45
+ * Provides built-in platform fields (id, object, created, updated, livemode)
46
+ * and a typed `fields` container for user-defined fields. The generic parameter
47
+ * `T` describes the shape of user fields accessible via `this.fields`.
48
+ *
49
+ * @remarks
50
+ * **Definite assignment assertions (`!`)**: All platform fields (`id`, `object`,
51
+ * `created`, `updated`, `livemode`, `fields`) use the TypeScript definite assignment
52
+ * assertion operator. This suppresses the "property has no initializer" error because
53
+ * these fields are intentionally left unset by the zero-argument constructor.
54
+ *
55
+ * The runtime (`executeInstanceMethod` in `invoke.ts`) is solely responsible for
56
+ * populating these fields via `Object.assign` and `hydrateInstance` **before** the
57
+ * dirty-tracking proxy is installed. Code that constructs a subclass directly
58
+ * (bypassing the runtime) will have `undefined` values for all platform fields at
59
+ * runtime, despite the types suggesting otherwise.
60
+ *
61
+ * @typeParam T - Shape of user-defined fields stored in `fields`
62
+ * @public
63
+ */
64
+ export declare abstract class BaseObject<T extends Record<string, unknown> = Record<string, unknown>> {
65
+ /** Unique identifier assigned by the platform */
66
+ readonly id: string;
67
+ /** Object type identifier assigned by the platform */
68
+ readonly object: string;
69
+ /** Timestamp when the object was created */
70
+ readonly created: Date;
71
+ /** Timestamp when the object was last updated */
72
+ readonly updated: Date;
73
+ /** Whether the object exists in live mode (true) or test mode (false). @public */
74
+ readonly livemode: boolean;
75
+ /**
76
+ * User-defined fields container. Populated during hydration via Object.assign
77
+ * before the dirty-tracking proxy is installed.
78
+ * Access individual fields as `this.fields.fieldName`.
79
+ *
80
+ * @remarks
81
+ * The generic type `T` describes the shape of available fields after
82
+ * hydration, not at construction time. Fields may be undefined before
83
+ * the instance is hydrated with data from the platform.
84
+ *
85
+ * @public
86
+ */
87
+ readonly fields: T;
88
+ /**
89
+ * Flushes pending field mutations into the slated-updates accumulator.
90
+ *
91
+ * When called from a transformed action (no save handler configured), this
92
+ * records which fields were mutated so that the Logic wrapper can include them
93
+ * in the response envelope's `updatedFields`. No network call is made.
94
+ *
95
+ * When a save handler is configured (runtime invoke path), the handler is
96
+ * called for actual persistence and its result is returned.
97
+ *
98
+ * @returns The save result including `updatedFieldCount` (unique fields flushed)
99
+ * @throws Error if the object is not proxied
100
+ * @public
101
+ */
102
+ save(): Promise<SaveResult>;
103
+ /**
104
+ * Discard all pending changes and restore field values to their
105
+ * last-saved state. Has no effect if the object is not proxied.
106
+ *
107
+ * @public
108
+ */
109
+ revert(): void;
110
+ }
111
+
112
+ /* Excluded from this release type: _buildMethodResponse */
113
+
114
+ /* Excluded from this release type: _clearRegistry */
115
+
116
+ /* Excluded from this release type: _clearSlatedUpdates */
117
+
118
+ /* Excluded from this release type: _commitProxyState */
119
+
120
+ /* Excluded from this release type: _createEventEmitter */
121
+
122
+ /* Excluded from this release type: _createInstanceProxy */
123
+
124
+ /* Excluded from this release type: _CreateProxyOptions */
125
+
126
+ /**
127
+ * Marks a class as a custom fields container for a custom object.
128
+ *
129
+ * This decorator is **inert at runtime** — it does not modify the class in any way.
130
+ * It serves as a marker for the build-time transformer, which discovers the fields
131
+ * class by this decorator and extracts field metadata from its members.
132
+ *
133
+ * The fields class must contain only field declarations (no methods). Use
134
+ * TSDoc tags from `@stripe/extensibility-jsonschema` on each field to control
135
+ * display and validation. Exactly one field should be tagged `primaryField`
136
+ * and at most one `secondaryField`.
137
+ *
138
+ * @public
139
+ */
140
+ export declare function CustomFields(_target: new (...args: unknown[]) => unknown, _context: ClassDecoratorContext): void;
141
+
142
+ /**
143
+ * Marks a class as a custom object type.
144
+ *
145
+ * This decorator is **inert at runtime** — it does not modify the class in any way.
146
+ * It serves as a marker for the build-time transformer, which extracts metadata
147
+ * and generates the necessary platform registration code.
148
+ *
149
+ * All naming metadata is expressed via TSDoc annotation tags in a JSDoc comment
150
+ * on the class: `@apiName`, `@displayName`, `@description`.
151
+ *
152
+ * @example
153
+ * Use TSDoc tags in a JSDoc comment above the decorator,
154
+ * e.g. `@apiName installment_plan` and `@displayName Installment plan`,
155
+ * then apply the bare decorator `@CustomObject`.
156
+ *
157
+ * @public
158
+ */
159
+ export declare function CustomObject(_target: new (...args: unknown[]) => unknown, _context: ClassDecoratorContext): void;
160
+
161
+ /* Excluded from this release type: _CustomObjectConstructor */
162
+
163
+ /* Excluded from this release type: _executeMethod */
164
+
165
+ /* Excluded from this release type: _ExecuteMethodOptions */
166
+
167
+ /* Excluded from this release type: _ExecuteMethodRequest */
168
+
169
+ /* Excluded from this release type: _getProxyState */
170
+
171
+ /* Excluded from this release type: _getRegisteredApiNames */
172
+
173
+ /* Excluded from this release type: _getRegisteredClass */
174
+
175
+ /* Excluded from this release type: _getSlatedUpdates */
176
+
177
+ /* Excluded from this release type: _hasProxyState */
178
+
179
+ /* Excluded from this release type: _INSTANCE_CONTEXT */
180
+
181
+ /* Excluded from this release type: _InstanceContext */
182
+
183
+ /**
184
+ * Context type that restricts decorator application to instance methods only.
185
+ * Uses `{ readonly static: false }` to make TypeScript reject `@Action` on static methods.
186
+ *
187
+ * @public
188
+ */
189
+ export declare type InstanceMethodDecoratorContext = { readonly static: false } & ClassMethodDecoratorContext;
190
+
191
+ /* Excluded from this release type: _InvokeBeginEvent */
192
+
193
+ /* Excluded from this release type: _InvokeCompleteEvent */
194
+
195
+ /* Excluded from this release type: _InvokeErrorEvent */
196
+
197
+ /* Excluded from this release type: _isTrackedField */
198
+
199
+ /* Excluded from this release type: _persistObject */
200
+
201
+ /* Excluded from this release type: _PersistOptions */
202
+
203
+ /* Excluded from this release type: _PlatformMetadata */
204
+
205
+ /* Excluded from this release type: _ProxiedObject */
206
+
207
+ /* Excluded from this release type: _PROXY_STATE */
208
+
209
+ /* Excluded from this release type: _ProxySetEvent */
210
+
211
+ /* Excluded from this release type: _ProxyState */
212
+
213
+ /* Excluded from this release type: _registerClass */
214
+
215
+ /* Excluded from this release type: _RuntimeEvent */
216
+
217
+ /* Excluded from this release type: _RuntimeEventEmitter */
218
+
219
+ /* Excluded from this release type: _SaveBeginEvent */
220
+
221
+ /* Excluded from this release type: _SaveCompleteEvent */
222
+
223
+ /* Excluded from this release type: _SaveHandler */
224
+
225
+ /**
226
+ * Result returned from save operations.
227
+ *
228
+ * @public
229
+ */
230
+ export declare interface SaveResult {
231
+ /** Number of fields updated */
232
+ updatedFieldCount: number;
233
+ }
234
+
235
+ /* Excluded from this release type: _SpanBeginEvent */
236
+
237
+ /* Excluded from this release type: _SpanEndEvent */
238
+
239
+ /* Excluded from this release type: _SpanErrorEvent */
240
+
241
+ /* Excluded from this release type: _UNTRACKED_FIELDS */
242
+
243
+ /* Excluded from this release type: _UpdateFrame */
244
+
245
+ export { }