@alien_org/contract 0.1.1 → 0.1.2

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 (3) hide show
  1. package/dist/index.d.cts +96 -28
  2. package/dist/index.d.mts +96 -28
  3. package/package.json +1 -1
package/dist/index.d.cts CHANGED
@@ -44,6 +44,49 @@ type If<Cond extends boolean, True, False> = Cond extends true ? True : False;
44
44
  * // Empty = {}
45
45
  */
46
46
  type Empty = Record<string, never>;
47
+ /**
48
+ * Client-side payment error codes (pre-broadcast failures).
49
+ * Returned when `status` is `'failed'` in `payment:response`.
50
+ * These errors occur before transaction broadcast, so no webhook is sent.
51
+ * @since 0.1.1
52
+ * @schema
53
+ */
54
+ type PaymentErrorCode = 'insufficient_balance' | 'network_error' | 'pre_checkout_rejected' | 'pre_checkout_timeout' | 'unknown';
55
+ /**
56
+ * Webhook status for payment results (on-chain truth).
57
+ * - `'finalized'`: Transaction confirmed on-chain
58
+ * - `'failed'`: Transaction failed on-chain
59
+ * @since 0.1.2
60
+ * @schema
61
+ */
62
+ type PaymentWebhookStatus = 'finalized' | 'failed';
63
+ /**
64
+ * Payment test scenarios for simulating different payment outcomes.
65
+ *
66
+ * | Scenario | Client sees | Webhook |
67
+ * |----------|-------------|---------|
68
+ * | `'paid'` | `paid` | `{ status: 'finalized' }` |
69
+ * | `'paid:failed'` | `paid` | `{ status: 'failed' }` |
70
+ * | `'cancelled'` | `cancelled` | none |
71
+ * | `'error:*'` | `failed` | none (pre-broadcast) |
72
+ *
73
+ * @example
74
+ * // Happy path: client paid, tx finalized
75
+ * test: 'paid'
76
+ *
77
+ * // On-chain failure: client paid, tx failed
78
+ * test: 'paid:failed'
79
+ *
80
+ * // User cancelled before confirming
81
+ * test: 'cancelled'
82
+ *
83
+ * // Pre-broadcast error (no tx, no webhook)
84
+ * test: 'error:insufficient_balance'
85
+ *
86
+ * @since 0.1.2
87
+ * @schema
88
+ */
89
+ type PaymentTestScenario = 'paid' | 'paid:failed' | 'cancelled' | `error:${PaymentErrorCode}`;
47
90
  //#endregion
48
91
  //#region src/events/types/payload.d.ts
49
92
  /**
@@ -91,11 +134,11 @@ interface Events {
91
134
  * Payment status.
92
135
  * - `paid`: Success
93
136
  * - `cancelled`: User rejected
94
- * - `failed`: Error (check `errorCode`)
137
+ * - `error`: Error (check `errorCode`)
95
138
  * @since 0.1.1
96
139
  * @schema
97
140
  */
98
- status: 'paid' | 'cancelled' | 'failed';
141
+ status: 'paid' | 'cancelled' | 'error';
99
142
  /**
100
143
  * Transaction hash (present when status is 'paid').
101
144
  * @since 0.1.1
@@ -112,7 +155,7 @@ interface Events {
112
155
  * @since 0.1.1
113
156
  * @schema
114
157
  */
115
- errorCode?: 'insufficient_balance' | 'network_error' | 'pre_checkout_rejected' | 'pre_checkout_timeout' | 'unknown';
158
+ errorCode?: PaymentErrorCode;
116
159
  }>>;
117
160
  /**
118
161
  * Clipboard read response.
@@ -264,37 +307,62 @@ interface Methods {
264
307
  */
265
308
  invoice: string;
266
309
  /**
267
- * Item title shown on the approval screen.
268
- * @since 0.1.1
269
- * @schema
270
- */
271
- title?: string;
272
- /**
273
- * Item description/caption shown on the approval screen.
274
- * @since 0.1.1
275
- * @schema
276
- */
277
- caption?: string;
278
- /**
279
- * Item icon URL shown on the approval screen.
280
- * @since 0.1.1
281
- * @schema
282
- */
283
- iconUrl?: string;
284
- /**
285
- * Quantity of items being purchased.
310
+ * Optional item details shown on the approval screen.
286
311
  * @since 0.1.1
287
312
  * @schema
288
313
  */
289
- quantity?: number;
314
+ item?: {
315
+ /**
316
+ * Item title shown on the approval screen.
317
+ * @since 0.1.1
318
+ * @schema
319
+ */
320
+ title: string;
321
+ /**
322
+ * Item icon URL shown on the approval screen.
323
+ * @since 0.1.1
324
+ * @schema
325
+ */
326
+ iconUrl: string;
327
+ /**
328
+ * Quantity of items being purchased.
329
+ * @since 0.1.1
330
+ * @schema
331
+ */
332
+ quantity: number;
333
+ };
290
334
  /**
291
- * Test mode flag. When true, no real payment is processed.
292
- * The approval screen shows a test indicator, and webhooks
293
- * include `test: true`. Use for development and testing.
335
+ * Test mode. Simulates payment outcomes without real transactions.
336
+ *
337
+ * | Scenario | Client | Webhook |
338
+ * |----------|--------|---------|
339
+ * | `true` / `'paid'` | `paid` | `finalized` |
340
+ * | `'paid:failed'` | `paid` | `failed` |
341
+ * | `'cancelled'` | `cancelled` | none |
342
+ * | `'error:*'` | `failed` | none |
343
+ *
344
+ * **Pre-broadcast errors** (no webhook):
345
+ * `'error:insufficient_balance'`, `'error:network_error'`,
346
+ * `'error:pre_checkout_rejected'`, `'error:pre_checkout_timeout'`,
347
+ * `'error:unknown'`
348
+ *
349
+ * @example
350
+ * // Happy path
351
+ * test: 'paid'
352
+ *
353
+ * // Client shows success, but tx failed on-chain
354
+ * test: 'paid:failed'
355
+ *
356
+ * // User cancelled
357
+ * test: 'cancelled'
358
+ *
359
+ * // Pre-broadcast failure
360
+ * test: 'error:insufficient_balance'
361
+ *
294
362
  * @since 0.1.1
295
363
  * @schema
296
364
  */
297
- test?: boolean;
365
+ test?: boolean | PaymentTestScenario;
298
366
  }>>;
299
367
  /**
300
368
  * Write text to the system clipboard.
@@ -364,4 +432,4 @@ declare function isMethodSupported(method: MethodName, version: Version): boolea
364
432
  */
365
433
  declare function getMethodMinVersion(method: MethodName): Version | undefined;
366
434
  //#endregion
367
- export { type CreateEventPayload, type CreateMethodPayload, type EventName, type EventPayload, type Events, type LaunchParams, type MethodName, type MethodNameWithVersionedPayload, type MethodPayload, type MethodVersionedPayload, type Methods, PLATFORMS, type Platform, type Version, getMethodMinVersion, getReleaseVersion, isMethodSupported, releases };
435
+ export { type CreateEventPayload, type CreateMethodPayload, type EventName, type EventPayload, type Events, type LaunchParams, type MethodName, type MethodNameWithVersionedPayload, type MethodPayload, type MethodVersionedPayload, type Methods, PLATFORMS, type PaymentErrorCode, type PaymentTestScenario, type PaymentWebhookStatus, type Platform, type Version, getMethodMinVersion, getReleaseVersion, isMethodSupported, releases };
package/dist/index.d.mts CHANGED
@@ -44,6 +44,49 @@ type If<Cond extends boolean, True, False> = Cond extends true ? True : False;
44
44
  * // Empty = {}
45
45
  */
46
46
  type Empty = Record<string, never>;
47
+ /**
48
+ * Client-side payment error codes (pre-broadcast failures).
49
+ * Returned when `status` is `'failed'` in `payment:response`.
50
+ * These errors occur before transaction broadcast, so no webhook is sent.
51
+ * @since 0.1.1
52
+ * @schema
53
+ */
54
+ type PaymentErrorCode = 'insufficient_balance' | 'network_error' | 'pre_checkout_rejected' | 'pre_checkout_timeout' | 'unknown';
55
+ /**
56
+ * Webhook status for payment results (on-chain truth).
57
+ * - `'finalized'`: Transaction confirmed on-chain
58
+ * - `'failed'`: Transaction failed on-chain
59
+ * @since 0.1.2
60
+ * @schema
61
+ */
62
+ type PaymentWebhookStatus = 'finalized' | 'failed';
63
+ /**
64
+ * Payment test scenarios for simulating different payment outcomes.
65
+ *
66
+ * | Scenario | Client sees | Webhook |
67
+ * |----------|-------------|---------|
68
+ * | `'paid'` | `paid` | `{ status: 'finalized' }` |
69
+ * | `'paid:failed'` | `paid` | `{ status: 'failed' }` |
70
+ * | `'cancelled'` | `cancelled` | none |
71
+ * | `'error:*'` | `failed` | none (pre-broadcast) |
72
+ *
73
+ * @example
74
+ * // Happy path: client paid, tx finalized
75
+ * test: 'paid'
76
+ *
77
+ * // On-chain failure: client paid, tx failed
78
+ * test: 'paid:failed'
79
+ *
80
+ * // User cancelled before confirming
81
+ * test: 'cancelled'
82
+ *
83
+ * // Pre-broadcast error (no tx, no webhook)
84
+ * test: 'error:insufficient_balance'
85
+ *
86
+ * @since 0.1.2
87
+ * @schema
88
+ */
89
+ type PaymentTestScenario = 'paid' | 'paid:failed' | 'cancelled' | `error:${PaymentErrorCode}`;
47
90
  //#endregion
48
91
  //#region src/events/types/payload.d.ts
49
92
  /**
@@ -91,11 +134,11 @@ interface Events {
91
134
  * Payment status.
92
135
  * - `paid`: Success
93
136
  * - `cancelled`: User rejected
94
- * - `failed`: Error (check `errorCode`)
137
+ * - `error`: Error (check `errorCode`)
95
138
  * @since 0.1.1
96
139
  * @schema
97
140
  */
98
- status: 'paid' | 'cancelled' | 'failed';
141
+ status: 'paid' | 'cancelled' | 'error';
99
142
  /**
100
143
  * Transaction hash (present when status is 'paid').
101
144
  * @since 0.1.1
@@ -112,7 +155,7 @@ interface Events {
112
155
  * @since 0.1.1
113
156
  * @schema
114
157
  */
115
- errorCode?: 'insufficient_balance' | 'network_error' | 'pre_checkout_rejected' | 'pre_checkout_timeout' | 'unknown';
158
+ errorCode?: PaymentErrorCode;
116
159
  }>>;
117
160
  /**
118
161
  * Clipboard read response.
@@ -264,37 +307,62 @@ interface Methods {
264
307
  */
265
308
  invoice: string;
266
309
  /**
267
- * Item title shown on the approval screen.
268
- * @since 0.1.1
269
- * @schema
270
- */
271
- title?: string;
272
- /**
273
- * Item description/caption shown on the approval screen.
274
- * @since 0.1.1
275
- * @schema
276
- */
277
- caption?: string;
278
- /**
279
- * Item icon URL shown on the approval screen.
280
- * @since 0.1.1
281
- * @schema
282
- */
283
- iconUrl?: string;
284
- /**
285
- * Quantity of items being purchased.
310
+ * Optional item details shown on the approval screen.
286
311
  * @since 0.1.1
287
312
  * @schema
288
313
  */
289
- quantity?: number;
314
+ item?: {
315
+ /**
316
+ * Item title shown on the approval screen.
317
+ * @since 0.1.1
318
+ * @schema
319
+ */
320
+ title: string;
321
+ /**
322
+ * Item icon URL shown on the approval screen.
323
+ * @since 0.1.1
324
+ * @schema
325
+ */
326
+ iconUrl: string;
327
+ /**
328
+ * Quantity of items being purchased.
329
+ * @since 0.1.1
330
+ * @schema
331
+ */
332
+ quantity: number;
333
+ };
290
334
  /**
291
- * Test mode flag. When true, no real payment is processed.
292
- * The approval screen shows a test indicator, and webhooks
293
- * include `test: true`. Use for development and testing.
335
+ * Test mode. Simulates payment outcomes without real transactions.
336
+ *
337
+ * | Scenario | Client | Webhook |
338
+ * |----------|--------|---------|
339
+ * | `true` / `'paid'` | `paid` | `finalized` |
340
+ * | `'paid:failed'` | `paid` | `failed` |
341
+ * | `'cancelled'` | `cancelled` | none |
342
+ * | `'error:*'` | `failed` | none |
343
+ *
344
+ * **Pre-broadcast errors** (no webhook):
345
+ * `'error:insufficient_balance'`, `'error:network_error'`,
346
+ * `'error:pre_checkout_rejected'`, `'error:pre_checkout_timeout'`,
347
+ * `'error:unknown'`
348
+ *
349
+ * @example
350
+ * // Happy path
351
+ * test: 'paid'
352
+ *
353
+ * // Client shows success, but tx failed on-chain
354
+ * test: 'paid:failed'
355
+ *
356
+ * // User cancelled
357
+ * test: 'cancelled'
358
+ *
359
+ * // Pre-broadcast failure
360
+ * test: 'error:insufficient_balance'
361
+ *
294
362
  * @since 0.1.1
295
363
  * @schema
296
364
  */
297
- test?: boolean;
365
+ test?: boolean | PaymentTestScenario;
298
366
  }>>;
299
367
  /**
300
368
  * Write text to the system clipboard.
@@ -364,4 +432,4 @@ declare function isMethodSupported(method: MethodName, version: Version): boolea
364
432
  */
365
433
  declare function getMethodMinVersion(method: MethodName): Version | undefined;
366
434
  //#endregion
367
- export { type CreateEventPayload, type CreateMethodPayload, type EventName, type EventPayload, type Events, type LaunchParams, type MethodName, type MethodNameWithVersionedPayload, type MethodPayload, type MethodVersionedPayload, type Methods, PLATFORMS, type Platform, type Version, getMethodMinVersion, getReleaseVersion, isMethodSupported, releases };
435
+ export { type CreateEventPayload, type CreateMethodPayload, type EventName, type EventPayload, type Events, type LaunchParams, type MethodName, type MethodNameWithVersionedPayload, type MethodPayload, type MethodVersionedPayload, type Methods, PLATFORMS, type PaymentErrorCode, type PaymentTestScenario, type PaymentWebhookStatus, type Platform, type Version, getMethodMinVersion, getReleaseVersion, isMethodSupported, releases };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alien_org/contract",
3
- "version": "0.1.1",
3
+ "version": "0.1.2",
4
4
  "type": "module",
5
5
  "main": "./dist/index.cjs",
6
6
  "module": "./dist/index.mjs",