@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.
- package/dist/iap/account-token.d.ts +14 -0
- package/dist/iap/account-token.js +43 -0
- package/dist/iap/config.d.ts +18 -0
- package/dist/iap/config.js +99 -0
- package/dist/iap/errors.d.ts +89 -0
- package/dist/iap/errors.js +66 -0
- package/dist/iap/errors.types.d.ts +74 -0
- package/dist/iap/errors.types.js +7 -0
- package/dist/iap/events/emitter.d.ts +28 -0
- package/dist/iap/events/emitter.js +33 -0
- package/dist/iap/events/events.types.d.ts +124 -0
- package/dist/iap/events/events.types.js +1 -0
- package/dist/iap/iap.types.d.ts +618 -0
- package/dist/iap/iap.types.js +1 -0
- package/dist/iap/index.d.ts +120 -0
- package/dist/iap/index.js +140 -0
- package/dist/iap/ingest/device.d.ts +7 -0
- package/dist/iap/ingest/device.js +191 -0
- package/dist/iap/ingest/device.types.d.ts +80 -0
- package/dist/iap/ingest/device.types.js +1 -0
- package/dist/iap/ingest/mappers.d.ts +66 -0
- package/dist/iap/ingest/mappers.js +248 -0
- package/dist/iap/ingest/matrix.d.ts +55 -0
- package/dist/iap/ingest/matrix.js +202 -0
- package/dist/iap/ingest/notifications.d.ts +70 -0
- package/dist/iap/ingest/notifications.js +238 -0
- package/dist/iap/read/derive.d.ts +40 -0
- package/dist/iap/read/derive.js +112 -0
- package/dist/iap/read/read.d.ts +47 -0
- package/dist/iap/read/read.js +215 -0
- package/dist/iap/read/read.types.d.ts +174 -0
- package/dist/iap/read/read.types.js +1 -0
- package/dist/iap/runtime/base64.d.ts +34 -0
- package/dist/iap/runtime/base64.js +131 -0
- package/dist/iap/runtime/clock.d.ts +13 -0
- package/dist/iap/runtime/clock.js +11 -0
- package/dist/iap/runtime/webcrypto.d.ts +14 -0
- package/dist/iap/runtime/webcrypto.js +66 -0
- package/dist/iap/server-api/client.d.ts +16 -0
- package/dist/iap/server-api/client.js +140 -0
- package/dist/iap/server-api/jwt.d.ts +3 -0
- package/dist/iap/server-api/jwt.js +70 -0
- package/dist/iap/server-api/server-api.types.d.ts +155 -0
- package/dist/iap/server-api/server-api.types.js +12 -0
- package/dist/iap/store/collapse.d.ts +27 -0
- package/dist/iap/store/collapse.js +85 -0
- package/dist/iap/store/descriptors.d.ts +46 -0
- package/dist/iap/store/descriptors.js +90 -0
- package/dist/iap/store/entities-store.d.ts +43 -0
- package/dist/iap/store/entities-store.js +348 -0
- package/dist/iap/store/rows.types.d.ts +233 -0
- package/dist/iap/store/rows.types.js +1 -0
- package/dist/iap/store/schemas.d.ts +68 -0
- package/dist/iap/store/schemas.js +214 -0
- package/dist/iap/store/store-errors.d.ts +52 -0
- package/dist/iap/store/store-errors.js +103 -0
- package/dist/iap/store/store.types.d.ts +193 -0
- package/dist/iap/store/store.types.js +1 -0
- package/dist/iap/verify/apple-roots.d.ts +18 -0
- package/dist/iap/verify/apple-roots.js +121 -0
- package/dist/iap/verify/payload-checks.d.ts +30 -0
- package/dist/iap/verify/payload-checks.js +20 -0
- package/dist/iap/verify/verifier.d.ts +36 -0
- package/dist/iap/verify/verifier.js +161 -0
- package/dist/iap/verify/verify.types.d.ts +292 -0
- package/dist/iap/verify/verify.types.js +15 -0
- package/dist/iap/version.d.ts +13 -0
- package/dist/iap/version.js +13 -0
- package/dist/index.d.ts +11 -0
- package/dist/modules/functions.js +2 -6
- 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 {};
|