@base44-preview/sdk 0.8.48-pr.145.de7eff3 → 0.8.48-pr.276.4f760f9

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 (71) hide show
  1. package/dist/iap/account-token.d.ts +14 -0
  2. package/dist/iap/account-token.js +43 -0
  3. package/dist/iap/config.d.ts +18 -0
  4. package/dist/iap/config.js +99 -0
  5. package/dist/iap/errors.d.ts +89 -0
  6. package/dist/iap/errors.js +66 -0
  7. package/dist/iap/errors.types.d.ts +74 -0
  8. package/dist/iap/errors.types.js +7 -0
  9. package/dist/iap/events/emitter.d.ts +28 -0
  10. package/dist/iap/events/emitter.js +33 -0
  11. package/dist/iap/events/events.types.d.ts +124 -0
  12. package/dist/iap/events/events.types.js +1 -0
  13. package/dist/iap/iap.types.d.ts +618 -0
  14. package/dist/iap/iap.types.js +1 -0
  15. package/dist/iap/index.d.ts +120 -0
  16. package/dist/iap/index.js +140 -0
  17. package/dist/iap/ingest/device.d.ts +7 -0
  18. package/dist/iap/ingest/device.js +191 -0
  19. package/dist/iap/ingest/device.types.d.ts +80 -0
  20. package/dist/iap/ingest/device.types.js +1 -0
  21. package/dist/iap/ingest/mappers.d.ts +66 -0
  22. package/dist/iap/ingest/mappers.js +248 -0
  23. package/dist/iap/ingest/matrix.d.ts +55 -0
  24. package/dist/iap/ingest/matrix.js +202 -0
  25. package/dist/iap/ingest/notifications.d.ts +70 -0
  26. package/dist/iap/ingest/notifications.js +238 -0
  27. package/dist/iap/read/derive.d.ts +40 -0
  28. package/dist/iap/read/derive.js +112 -0
  29. package/dist/iap/read/read.d.ts +47 -0
  30. package/dist/iap/read/read.js +215 -0
  31. package/dist/iap/read/read.types.d.ts +174 -0
  32. package/dist/iap/read/read.types.js +1 -0
  33. package/dist/iap/runtime/base64.d.ts +34 -0
  34. package/dist/iap/runtime/base64.js +131 -0
  35. package/dist/iap/runtime/clock.d.ts +13 -0
  36. package/dist/iap/runtime/clock.js +11 -0
  37. package/dist/iap/runtime/webcrypto.d.ts +14 -0
  38. package/dist/iap/runtime/webcrypto.js +66 -0
  39. package/dist/iap/server-api/client.d.ts +16 -0
  40. package/dist/iap/server-api/client.js +140 -0
  41. package/dist/iap/server-api/jwt.d.ts +3 -0
  42. package/dist/iap/server-api/jwt.js +70 -0
  43. package/dist/iap/server-api/server-api.types.d.ts +155 -0
  44. package/dist/iap/server-api/server-api.types.js +12 -0
  45. package/dist/iap/store/collapse.d.ts +27 -0
  46. package/dist/iap/store/collapse.js +85 -0
  47. package/dist/iap/store/descriptors.d.ts +46 -0
  48. package/dist/iap/store/descriptors.js +90 -0
  49. package/dist/iap/store/entities-store.d.ts +43 -0
  50. package/dist/iap/store/entities-store.js +348 -0
  51. package/dist/iap/store/rows.types.d.ts +233 -0
  52. package/dist/iap/store/rows.types.js +1 -0
  53. package/dist/iap/store/schemas.d.ts +68 -0
  54. package/dist/iap/store/schemas.js +214 -0
  55. package/dist/iap/store/store-errors.d.ts +52 -0
  56. package/dist/iap/store/store-errors.js +103 -0
  57. package/dist/iap/store/store.types.d.ts +193 -0
  58. package/dist/iap/store/store.types.js +1 -0
  59. package/dist/iap/verify/apple-roots.d.ts +18 -0
  60. package/dist/iap/verify/apple-roots.js +121 -0
  61. package/dist/iap/verify/payload-checks.d.ts +30 -0
  62. package/dist/iap/verify/payload-checks.js +20 -0
  63. package/dist/iap/verify/verifier.d.ts +36 -0
  64. package/dist/iap/verify/verifier.js +161 -0
  65. package/dist/iap/verify/verify.types.d.ts +292 -0
  66. package/dist/iap/verify/verify.types.js +15 -0
  67. package/dist/iap/version.d.ts +13 -0
  68. package/dist/iap/version.js +13 -0
  69. package/dist/index.d.ts +11 -0
  70. package/dist/modules/functions.js +2 -6
  71. package/package.json +33 -3
@@ -0,0 +1,618 @@
1
+ /**
2
+ * Apple in-app purchase support for Base44 backend functions.
3
+ *
4
+ * Base44's iOS shell already speaks StoreKit 2 on the device. This module is
5
+ * the server half: it verifies what Apple signed, so your backend can decide
6
+ * who has paid for what without ever trusting the client.
7
+ *
8
+ * Everything here runs inside your app's own backend functions. Nothing is
9
+ * sent to a Base44 service, and no Apple credentials are needed to verify a
10
+ * purchase.
11
+ *
12
+ * ## Getting a client
13
+ *
14
+ * The runtime lives behind a subpath, so a browser bundle never downloads
15
+ * certificate-parsing code:
16
+ *
17
+ * ```typescript
18
+ * import { createClientFromRequest } from "npm:@base44/sdk";
19
+ * import { createIapClient } from "npm:@base44/sdk/iap";
20
+ *
21
+ * Deno.serve(async (req) => {
22
+ * const iap = createIapClient({
23
+ * base44: createClientFromRequest(req),
24
+ * config: {
25
+ * bundleId: "com.example.app",
26
+ * appAppleId: 1234567890,
27
+ * products: { pro_monthly: { type: "autoRenewableSubscription" } },
28
+ * },
29
+ * });
30
+ *
31
+ * const transaction = await iap.verifyTransaction(jws);
32
+ * return Response.json({ productId: transaction.productId });
33
+ * });
34
+ * ```
35
+ *
36
+ * ## Authentication Modes
37
+ *
38
+ * This module is only available in Base44-hosted backend functions, from a
39
+ * client created with
40
+ * {@linkcode createClientFromRequest | createClientFromRequest()}.
41
+ */
42
+ import type { DecodedNotification, DecodedRenewalInfo, DecodedTransaction } from "./verify/verify.types.js";
43
+ import type { IapEventHandler } from "./events/events.types.js";
44
+ import type { HandleNotificationResult } from "./ingest/notifications.js";
45
+ import type { RecordTransactionOptions, RecordTransactionResult, SyncPayload, SyncResult } from "./ingest/device.types.js";
46
+ import type { IapEntityName } from "./store/schemas.js";
47
+ import type { IapServerApiConfig, IapServerApiModule } from "./server-api/server-api.types.js";
48
+ import type { IapConsumptionRequestRecord, IapTransactionRecord } from "./store/rows.types.js";
49
+ import type { EntitlementQuery, Entitlements, SubscriptionQuery, SubscriptionState, TransactionQuery } from "./read/read.types.js";
50
+ /** What kind of product an identifier refers to. */
51
+ export type IapConfiguredProductType =
52
+ /** Used up and bought again, like a pack of coins. */
53
+ "consumable"
54
+ /** Bought once and owned forever, like unlocking a feature. */
55
+ | "nonConsumable"
56
+ /**
57
+ * Bought for a fixed period that does not renew itself.
58
+ *
59
+ * Apple does not track when these end, so `nonRenewingDurationDays` is
60
+ * required and this SDK computes the expiry from it.
61
+ */
62
+ | "nonRenewingSubscription"
63
+ /** Renews itself until cancelled. */
64
+ | "autoRenewableSubscription";
65
+ /** One product the app sells. */
66
+ export interface IapProductConfig {
67
+ /** What kind of product this is. */
68
+ type: IapConfiguredProductType;
69
+ /**
70
+ * The subscription group this product belongs to.
71
+ *
72
+ * Products in one group are alternatives to each other, so a customer can
73
+ * hold only one at a time. Auto-renewable subscriptions only.
74
+ */
75
+ subscriptionGroupId?: string;
76
+ /**
77
+ * How many days a non-renewing subscription lasts.
78
+ *
79
+ * Required for `nonRenewingSubscription` and ignored otherwise. Apple never
80
+ * expires these, so this number is the only thing that says when access
81
+ * ends.
82
+ */
83
+ nonRenewingDurationDays?: number;
84
+ }
85
+ /**
86
+ * How the in-app purchase module behaves for one app.
87
+ *
88
+ * `bundleId` and `appAppleId` are two different things and both are needed:
89
+ * the bundle id is the reverse-DNS string like `com.example.app`, while the
90
+ * App Store id is the number shown in App Store Connect under App Information.
91
+ * Apple omits the numeric id from sandbox payloads, so it is only enforced
92
+ * against production tokens.
93
+ */
94
+ export interface IapConfig {
95
+ /** The app's bundle identifier, e.g. `"com.example.app"`. */
96
+ bundleId: string;
97
+ /**
98
+ * The app's numeric App Store id.
99
+ *
100
+ * Find it in App Store Connect under App Information, labelled "Apple ID".
101
+ * It is not the bundle id.
102
+ */
103
+ appAppleId: number;
104
+ /** Every product the app sells, keyed by product identifier. */
105
+ products: Record<string, IapProductConfig>;
106
+ /**
107
+ * Whether purchases made in Apple's sandbox count as real.
108
+ *
109
+ * Turn this on while testing and off in production. With it off, a sandbox
110
+ * token is rejected outright.
111
+ *
112
+ * @defaultValue `false`
113
+ */
114
+ testMode?: boolean;
115
+ /**
116
+ * Whether to accept tokens from Xcode's local StoreKit testing.
117
+ *
118
+ * These are signed by Xcode rather than by Apple, so they cannot be verified
119
+ * against Apple's certificates — turning this on skips that check for them.
120
+ * Never turn it on in production.
121
+ *
122
+ * @defaultValue `false`
123
+ */
124
+ allowLocalTesting?: boolean;
125
+ /**
126
+ * Credentials for calling Apple's own servers.
127
+ *
128
+ * Optional, and not needed to verify a purchase or check an entitlement. It
129
+ * unlocks answering refund-consumption requests and sending test
130
+ * notifications. Use an **In-App Purchase key** from App Store Connect, kept
131
+ * in Base44 secrets.
132
+ */
133
+ serverApi?: IapServerApiConfig;
134
+ /**
135
+ * Whether to ask Apple's servers whether a certificate has been revoked.
136
+ *
137
+ * Not implemented in this version. Setting it to `true` throws when the
138
+ * client is created, rather than quietly behaving as if it were `false`.
139
+ *
140
+ * @defaultValue `false`
141
+ */
142
+ onlineChecks?: boolean;
143
+ }
144
+ /** Whether the app is set up to store purchase data. */
145
+ export interface IapSetupReport {
146
+ /** Whether everything the module needs exists. */
147
+ ok: boolean;
148
+ /**
149
+ * Entities the app is missing.
150
+ *
151
+ * Create them from `IAP_ENTITY_SCHEMAS`. Until they exist, nothing can be
152
+ * stored and every entitlement check answers "not entitled".
153
+ */
154
+ missingEntities: IapEntityName[];
155
+ /** What the app owner still has to do, in order. */
156
+ checklist: readonly string[];
157
+ }
158
+ /**
159
+ * The in-app purchase module.
160
+ *
161
+ * Every method that takes a signed token throws if it cannot verify it. There
162
+ * is no partially-verified result: a token either passed every check Apple
163
+ * describes, or it is rejected.
164
+ */
165
+ export interface IapModule {
166
+ /**
167
+ * Verifies a signed transaction and returns its contents.
168
+ *
169
+ * Checks the signature, walks the certificate chain to a pinned Apple root,
170
+ * and confirms the transaction is for this app and from an environment this
171
+ * app accepts.
172
+ *
173
+ * @param jws - The signed transaction, as Apple or StoreKit produced it.
174
+ * @returns Promise resolving to the decoded transaction.
175
+ * @throws {Error} An `IapVerificationError` when the token fails any check. Its `code` says which.
176
+ *
177
+ * @example Verify a purchase reported by the app
178
+ * ```typescript
179
+ * // Verify a purchase reported by the app
180
+ * const transaction = await iap.verifyTransaction(jws);
181
+ * console.log(transaction.productId, transaction.expiresDate);
182
+ * ```
183
+ *
184
+ * @example Tell rejection reasons apart
185
+ * ```typescript
186
+ * // Tell rejection reasons apart
187
+ * try {
188
+ * await iap.verifyTransaction(jws);
189
+ * } catch (error) {
190
+ * if (error.code === "INVALID_APP_IDENTIFIER") {
191
+ * // The token is genuine, but it belongs to a different app.
192
+ * }
193
+ * }
194
+ * ```
195
+ */
196
+ verifyTransaction(jws: string): Promise<DecodedTransaction>;
197
+ /**
198
+ * Verifies signed subscription renewal information and returns its contents.
199
+ *
200
+ * Renewal information is where a subscription's future lives — whether it
201
+ * will renew, what it will renew to, and whether it is inside a billing
202
+ * grace period. A plain transaction carries none of that.
203
+ *
204
+ * @param jws - The signed renewal information.
205
+ * @returns Promise resolving to the decoded renewal information.
206
+ * @throws {Error} An `IapVerificationError` when the token fails any check.
207
+ *
208
+ * @example
209
+ * ```typescript
210
+ * // Read whether a subscription will renew
211
+ * const renewal = await iap.verifyRenewalInfo(jws);
212
+ * const willRenew = renewal.autoRenewStatus === 1;
213
+ * ```
214
+ */
215
+ verifyRenewalInfo(jws: string): Promise<DecodedRenewalInfo>;
216
+ /**
217
+ * Verifies an App Store Server Notification and returns its contents.
218
+ *
219
+ * Notifications arrive as one signed envelope wrapping further signed
220
+ * tokens. Each is verified in its own right, and the decoded transaction and
221
+ * renewal information are returned in place of the raw strings, so no caller
222
+ * can act on something unverified by mistake.
223
+ *
224
+ * @param signedPayload - The `signedPayload` value from Apple's request body.
225
+ * @returns Promise resolving to the decoded notification.
226
+ * @throws {Error} An `IapVerificationError` when the envelope or any inner token fails a check.
227
+ *
228
+ * @example
229
+ * ```typescript
230
+ * // Handle a notification from Apple
231
+ * const { signedPayload } = await req.json();
232
+ * const notification = await iap.verifyNotification(signedPayload);
233
+ *
234
+ * if (notification.notificationType === "REFUND") {
235
+ * const transactionId = notification.data?.transactionInfo?.transactionId;
236
+ * // Take the purchase back.
237
+ * }
238
+ * ```
239
+ */
240
+ verifyNotification(signedPayload: string): Promise<DecodedNotification>;
241
+ /**
242
+ * Turns a Base44 user id into the UUID to attach to a purchase.
243
+ *
244
+ * StoreKit lets the app tag a purchase with a UUID, and Apple signs that
245
+ * value back into every resulting transaction — which is what makes a
246
+ * purchase attributable to a user without trusting anything the client says.
247
+ *
248
+ * The mapping is a pure function, so the app, the shell and the backend all
249
+ * derive the same UUID from the same user id with nothing stored in between.
250
+ *
251
+ * @param base44UserId - The Base44 user id.
252
+ * @returns The UUID to pass to StoreKit as the purchase's account token.
253
+ *
254
+ * @example
255
+ * ```typescript
256
+ * // Derive the token the shell should attach to a purchase
257
+ * const token = iap.appAccountTokenFor(user.id);
258
+ * ```
259
+ */
260
+ appAccountTokenFor(base44UserId: string): string;
261
+ /**
262
+ * Handles an App Store Server Notification from Apple.
263
+ *
264
+ * Point your notification function at this and return what it gives you.
265
+ * It owns the whole contract with Apple, including the status code — which
266
+ * matters more than it looks: Apple retries a failure for up to 72 hours but
267
+ * **never** retries a success, so a `200` sent before the data is stored
268
+ * loses that notification permanently. This never does that.
269
+ *
270
+ * The payload is verified, stored raw, applied, and only then reported as
271
+ * handled. A repeat delivery of something already handled is recognised and
272
+ * ignored. Any storage failure produces `503`, so Apple comes back.
273
+ *
274
+ * @param request - The incoming request from Apple.
275
+ * @returns Promise resolving to the response to return: `200` handled, `400` malformed, `401` unverifiable, `503` try again.
276
+ *
277
+ * @example
278
+ * ```typescript
279
+ * // The whole notification function
280
+ * import { createClientFromRequest } from "npm:@base44/sdk";
281
+ * import { createIapClient } from "npm:@base44/sdk/iap";
282
+ * import { iapConfig } from "./iapConfig.ts";
283
+ *
284
+ * Deno.serve(async (req) => {
285
+ * const iap = createIapClient({ base44: createClientFromRequest(req), config: iapConfig });
286
+ * return await iap.handleNotification(req);
287
+ * });
288
+ * ```
289
+ *
290
+ * @example
291
+ * ```typescript
292
+ * // React to what arrived
293
+ * iap.onEvent(async (event) => {
294
+ * if (event.type === "purchase.refund_reversed") {
295
+ * await reinstate(event.appUserId, event.productId);
296
+ * }
297
+ * });
298
+ *
299
+ * return await iap.handleNotification(req);
300
+ * ```
301
+ */
302
+ handleNotification(request: Request): Promise<Response>;
303
+ /**
304
+ * Handles a signed notification payload directly, without an HTTP request.
305
+ *
306
+ * Useful for replaying a payload you already stored, and for testing. It
307
+ * runs exactly the same path as {@linkcode IapModule.handleNotification | handleNotification()},
308
+ * including duplicate detection, so replaying something already applied
309
+ * changes nothing.
310
+ *
311
+ * @param signedPayload - The `signedPayload` string from Apple's request body.
312
+ * @returns Promise resolving to what was done, including the status a webhook would have returned.
313
+ *
314
+ * @example
315
+ * ```typescript
316
+ * // Replay a stored payload
317
+ * const stored = await base44.asServiceRole.entities.IapNotification.get(id);
318
+ * const result = await iap.handleSignedPayload(stored.rawSignedPayload);
319
+ * console.log(result.status, result.outcome);
320
+ * ```
321
+ */
322
+ handleSignedPayload(signedPayload: string): Promise<HandleNotificationResult>;
323
+ /**
324
+ * Registers a handler called after purchase data has been stored.
325
+ *
326
+ * Handlers run once the write has landed, so anything they do — sending an
327
+ * email, granting a bonus, clawing back a balance — can rely on the data
328
+ * being there. A handler that throws is reported and ignored; it can never
329
+ * change what Apple is told.
330
+ *
331
+ * @param handler - Called with each event.
332
+ * @returns A function that removes the handler.
333
+ *
334
+ * @example
335
+ * ```typescript
336
+ * // Take content back on a refund, and give it back if reversed
337
+ * const stop = iap.onEvent(async (event) => {
338
+ * if (event.type === "purchase.refunded") {
339
+ * await revokeCoins(event.appUserId, event.productId);
340
+ * }
341
+ * if (event.type === "purchase.refund_reversed") {
342
+ * await grantCoins(event.appUserId, event.productId);
343
+ * }
344
+ * });
345
+ * ```
346
+ *
347
+ * @example
348
+ * ```typescript
349
+ * // Keep serving a customer whose payment failed but who is in a grace period
350
+ * iap.onEvent((event) => {
351
+ * if (event.type === "subscription.billing_issue" && event.inGracePeriod) {
352
+ * // Apple requires full service throughout the grace period.
353
+ * return;
354
+ * }
355
+ * });
356
+ * ```
357
+ */
358
+ onEvent(handler: IapEventHandler): () => void;
359
+ /**
360
+ * Checks whether the app can actually store purchase data.
361
+ *
362
+ * Never throws, so it is safe to call from a status page. Worth calling once
363
+ * after setup: until the four entities exist, nothing can be stored and
364
+ * every entitlement check answers "not entitled" — which looks exactly like
365
+ * an app with no paying customers.
366
+ *
367
+ * @returns Promise resolving to what exists, what is missing, and what to do about it.
368
+ *
369
+ * @example
370
+ * ```typescript
371
+ * // Confirm setup before going live
372
+ * const report = await iap.checkSetup();
373
+ * if (!report.ok) {
374
+ * console.error("missing entities:", report.missingEntities.join(", "));
375
+ * report.checklist.forEach((step, i) => console.log(`${i + 1}. ${step}`));
376
+ * }
377
+ * ```
378
+ */
379
+ checkSetup(): Promise<IapSetupReport>;
380
+ /**
381
+ * Whether a user should get a paid feature right now.
382
+ *
383
+ * **This is the one call a feature gate should make.** Never gate on
384
+ * anything the client sends: a purchase is only real if Apple signed it, and
385
+ * this is the only thing that knows whether it did.
386
+ *
387
+ * It never throws. No purchase, an unreadable stored token, a storage
388
+ * failure — every one of those answers `false`, because the alternative is a
389
+ * gate that opens when something breaks.
390
+ *
391
+ * Two subtleties it handles for you. A subscription in a billing **grace
392
+ * period** counts as entitled, because Apple requires full service until the
393
+ * grace period ends. Sandbox purchases only count when `testMode` is on, so
394
+ * a live app cannot be unlocked with a test purchase.
395
+ *
396
+ * @param appUserId - The Base44 user id.
397
+ * @param query - Optionally narrow to certain products or a subscription group.
398
+ * @returns Promise resolving to whether the user is entitled. Never rejects.
399
+ *
400
+ * @example
401
+ * ```typescript
402
+ * // Gate a paid feature
403
+ * if (!(await iap.hasActiveSubscription(user.id))) {
404
+ * return Response.json({ error: "Subscription required" }, { status: 402 });
405
+ * }
406
+ * ```
407
+ *
408
+ * @example
409
+ * ```typescript
410
+ * // Require one of several plans
411
+ * const entitled = await iap.hasActiveSubscription(user.id, {
412
+ * productIds: ["pro_monthly", "pro_yearly"],
413
+ * });
414
+ * ```
415
+ */
416
+ hasActiveSubscription(appUserId: string, query?: EntitlementQuery): Promise<boolean>;
417
+ /**
418
+ * Every subscription a user holds, and where each one stands.
419
+ *
420
+ * A user can hold more than one: a plan they bought, a plan a family member
421
+ * shared with them, or one per subscription group. Use this when you need to
422
+ * show a customer their own status; use
423
+ * {@linkcode IapModule.hasActiveSubscription | hasActiveSubscription()} to
424
+ * gate a feature.
425
+ *
426
+ * @param appUserId - The Base44 user id.
427
+ * @param query - Optionally narrow to a subscription group or product.
428
+ * @returns Promise resolving to one entry per subscription.
429
+ * @throws {Error} An `IapStoreError` when the data could not be read.
430
+ *
431
+ * @example
432
+ * ```typescript
433
+ * // Show a customer their subscription
434
+ * const [subscription] = await iap.getSubscriptionState(user.id);
435
+ * if (subscription?.status === "grace_period") {
436
+ * showBanner("There's a problem with your payment method.");
437
+ * }
438
+ * ```
439
+ *
440
+ * @example
441
+ * ```typescript
442
+ * // Notice a scheduled plan change
443
+ * for (const state of await iap.getSubscriptionState(user.id)) {
444
+ * if (state.autoRenewProductId && state.autoRenewProductId !== state.productId) {
445
+ * console.log(`switching to ${state.autoRenewProductId} at renewal`);
446
+ * }
447
+ * }
448
+ * ```
449
+ */
450
+ getSubscriptionState(appUserId: string, query?: SubscriptionQuery): Promise<SubscriptionState[]>;
451
+ /**
452
+ * Everything a user currently owns.
453
+ *
454
+ * The server-side counterpart of StoreKit's current entitlements: what they
455
+ * own outright, which fixed-period purchases are still running, and every
456
+ * subscription. Consumables never appear — once used up they are the app's
457
+ * business to track, and Apple leaves them out too.
458
+ *
459
+ * @param appUserId - The Base44 user id.
460
+ * @returns Promise resolving to what the user owns, and when it was worked out.
461
+ * @throws {Error} An `IapStoreError` when the data could not be read.
462
+ *
463
+ * @example
464
+ * ```typescript
465
+ * // Build a customer's library
466
+ * const owned = await iap.getEntitlements(user.id);
467
+ * const unlocked = owned.nonConsumables.map((item) => item.productId);
468
+ * const passes = owned.nonRenewingSubscriptions.filter((pass) => pass.active);
469
+ * ```
470
+ */
471
+ getEntitlements(appUserId: string): Promise<Entitlements>;
472
+ /**
473
+ * One stored purchase, by Apple's transaction id.
474
+ *
475
+ * @param transactionId - Apple's transaction id.
476
+ * @returns Promise resolving to the stored purchase, or `null` when there is none.
477
+ * @throws {Error} An `IapStoreError` when the data could not be read.
478
+ *
479
+ * @example
480
+ * ```typescript
481
+ * // Look up a purchase for a support request
482
+ * const purchase = await iap.getPurchase("2000000123456789");
483
+ * console.log(purchase?.productId, purchase?.revocationDate);
484
+ * ```
485
+ */
486
+ getPurchase(transactionId: string): Promise<IapTransactionRecord | null>;
487
+ /**
488
+ * A user's stored purchases, newest first.
489
+ *
490
+ * @param appUserId - The Base44 user id.
491
+ * @param query - Optionally narrow by product, type, date range, environment or refund state.
492
+ * @returns Promise resolving to the matching purchases.
493
+ * @throws {Error} An `IapStoreError` when the data could not be read.
494
+ *
495
+ * @example
496
+ * ```typescript
497
+ * // Show this month's purchases
498
+ * const purchases = await iap.listTransactions(user.id, {
499
+ * since: Date.UTC(2026, 8, 1),
500
+ * revoked: false,
501
+ * });
502
+ * ```
503
+ */
504
+ listTransactions(appUserId: string, query?: TransactionQuery): Promise<IapTransactionRecord[]>;
505
+ /**
506
+ * A user's refunded or revoked purchases.
507
+ *
508
+ * Each row carries how much was refunded, so an app that sold a consumable
509
+ * balance can take back the right proportion of it.
510
+ *
511
+ * @param appUserId - The Base44 user id.
512
+ * @returns Promise resolving to the refunded purchases.
513
+ * @throws {Error} An `IapStoreError` when the data could not be read.
514
+ *
515
+ * @example
516
+ * ```typescript
517
+ * // Claw back a coin balance proportionally
518
+ * for (const refund of await iap.listRefunds(user.id)) {
519
+ * const share = (refund.revocationPercentage ?? 100000) / 100000;
520
+ * await deductCoins(user.id, refund.productId, share);
521
+ * }
522
+ * ```
523
+ */
524
+ listRefunds(appUserId: string): Promise<IapTransactionRecord[]>;
525
+ /**
526
+ * Refund requests Apple is still waiting on, soonest deadline first.
527
+ *
528
+ * Apple allows 12 hours to answer in production and only **5 minutes** in
529
+ * sandbox, and only wants an answer if the customer consented to sharing
530
+ * their consumption data. With no consent flow, the right thing is to ignore
531
+ * these.
532
+ *
533
+ * @returns Promise resolving to the open requests, ordered by deadline.
534
+ * @throws {Error} An `IapStoreError` when the data could not be read.
535
+ *
536
+ * @example
537
+ * ```typescript
538
+ * // See what is waiting, and how long is left
539
+ * for (const request of await iap.listPendingConsumptionRequests()) {
540
+ * const minutesLeft = Math.round((request.deadlineAt - Date.now()) / 60000);
541
+ * console.log(request.transactionId, request.consumptionRequestReason, minutesLeft);
542
+ * }
543
+ * ```
544
+ */
545
+ listPendingConsumptionRequests(): Promise<IapConsumptionRequestRecord[]>;
546
+ /**
547
+ * Records a purchase the app has just made.
548
+ *
549
+ * **The app must not tell StoreKit the purchase is finished until this
550
+ * resolves.** An unfinished transaction is re-delivered at the next launch,
551
+ * so the device acts as the retry queue — and a purchase finished before the
552
+ * server stored it is a purchase nobody can prove afterwards. If this
553
+ * throws, deliver nothing and do not finish.
554
+ *
555
+ * `duplicate` is the double-delivery guard. StoreKit re-delivers an
556
+ * unfinished transaction every launch, so a consumable should only be
557
+ * granted when `duplicate` is `false`.
558
+ *
559
+ * Passing `appUserId` is worth doing: it is checked against the UUID Apple
560
+ * signed into the transaction, so one customer cannot claim another's
561
+ * purchase by replaying their token.
562
+ *
563
+ * @param jws - The signed transaction from StoreKit.
564
+ * @param options - Optionally the Base44 user making the request.
565
+ * @returns Promise resolving to what was stored, and whether it was already known.
566
+ * @throws {Error} An `IapVerificationError` when the token fails a check, or an `IapStoreError` when it could not be stored.
567
+ *
568
+ * @example
569
+ * ```typescript
570
+ * // Record a purchase, then let the app finish it
571
+ * const result = await iap.recordTransaction(jws, { appUserId: user.id });
572
+ * if (!result.duplicate) {
573
+ * await grantCoins(user.id, result.decoded.productId);
574
+ * }
575
+ * return Response.json(result);
576
+ * ```
577
+ */
578
+ recordTransaction(jws: string, options?: RecordTransactionOptions): Promise<RecordTransactionResult>;
579
+ /**
580
+ * Reconciles what the device knows about its purchases with what the server knows.
581
+ *
582
+ * Call this at launch, on foreground, after any purchase, and after a
583
+ * customer-initiated restore. It is how everything heals: a notification
584
+ * Apple never managed to deliver, a purchase made on another device, a
585
+ * renewal that happened while the app was closed.
586
+ *
587
+ * One unreadable token never fails the whole call — it is counted in
588
+ * `skipped` and the rest are stored, because the other purchases are still
589
+ * real. `mismatches` counts what the device believes it owns that the server
590
+ * does not; persistently above zero means notifications are going missing.
591
+ *
592
+ * @param payload - What the device knows: current entitlements, unfinished transactions, and subscription status pairs.
593
+ * @param options - Optionally the Base44 user making the request.
594
+ * @returns Promise resolving to which transactions are stored, what the server believes, and how far the two disagreed.
595
+ *
596
+ * @example
597
+ * ```typescript
598
+ * // The launch-time sync endpoint
599
+ * const result = await iap.syncEntitlements(await req.json(), { appUserId: user.id });
600
+ * return Response.json(result);
601
+ * // The app may now finish the transactions in result.recordedTransactionIds.
602
+ * ```
603
+ */
604
+ syncEntitlements(payload: SyncPayload, options?: RecordTransactionOptions): Promise<SyncResult>;
605
+ /**
606
+ * Calls to Apple's own servers.
607
+ *
608
+ * Always present. Every method throws until `serverApi` credentials are
609
+ * configured, so the module's shape never depends on configuration.
610
+ *
611
+ * @example
612
+ * ```typescript
613
+ * // Confirm the webhook is reachable
614
+ * const { testNotificationToken } = await iap.serverApi.requestTestNotification();
615
+ * ```
616
+ */
617
+ serverApi: IapServerApiModule;
618
+ }
@@ -0,0 +1 @@
1
+ export {};