primitive-admin 1.3.0-alpha.0 → 1.3.0-alpha.1

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 (135) hide show
  1. package/README.md +45 -0
  2. package/dist/src/commands/auth.js +32 -6
  3. package/dist/src/commands/auth.js.map +1 -1
  4. package/dist/src/commands/db3-types.d.ts +27 -0
  5. package/dist/src/commands/db3-types.js +288 -2
  6. package/dist/src/commands/db3-types.js.map +1 -1
  7. package/dist/src/commands/db3.d.ts +16 -2
  8. package/dist/src/commands/db3.js +614 -5
  9. package/dist/src/commands/db3.js.map +1 -1
  10. package/dist/src/commands/documents.js +7 -0
  11. package/dist/src/commands/documents.js.map +1 -1
  12. package/dist/src/commands/functions.js +8 -3
  13. package/dist/src/commands/functions.js.map +1 -1
  14. package/dist/src/commands/hosting.js +177 -14
  15. package/dist/src/commands/hosting.js.map +1 -1
  16. package/dist/src/commands/metadata.js +14 -6
  17. package/dist/src/commands/metadata.js.map +1 -1
  18. package/dist/src/commands/secrets.d.ts +38 -0
  19. package/dist/src/commands/secrets.js +102 -4
  20. package/dist/src/commands/secrets.js.map +1 -1
  21. package/dist/src/commands/spent-tokens.d.ts +19 -0
  22. package/dist/src/commands/spent-tokens.js +79 -0
  23. package/dist/src/commands/spent-tokens.js.map +1 -0
  24. package/dist/src/commands/sync-app-settings.d.ts +58 -0
  25. package/dist/src/commands/sync-app-settings.js +119 -2
  26. package/dist/src/commands/sync-app-settings.js.map +1 -1
  27. package/dist/src/commands/sync.d.ts +62 -2
  28. package/dist/src/commands/sync.js +295 -46
  29. package/dist/src/commands/sync.js.map +1 -1
  30. package/dist/src/commands/usage.d.ts +24 -0
  31. package/dist/src/commands/usage.js +54 -0
  32. package/dist/src/commands/usage.js.map +1 -1
  33. package/dist/src/commands/users.js +41 -1
  34. package/dist/src/commands/users.js.map +1 -1
  35. package/dist/src/lib/api-client.d.ts +165 -0
  36. package/dist/src/lib/api-client.js +134 -10
  37. package/dist/src/lib/api-client.js.map +1 -1
  38. package/dist/src/lib/app-settings-descriptor.d.ts +13 -1
  39. package/dist/src/lib/app-settings-descriptor.js +49 -1
  40. package/dist/src/lib/app-settings-descriptor.js.map +1 -1
  41. package/dist/src/lib/auth-flow.d.ts +13 -0
  42. package/dist/src/lib/auth-flow.js +23 -2
  43. package/dist/src/lib/auth-flow.js.map +1 -1
  44. package/dist/src/lib/command-groups.js +2 -0
  45. package/dist/src/lib/command-groups.js.map +1 -1
  46. package/dist/src/lib/config-object-descriptor.js +6 -1
  47. package/dist/src/lib/config-object-descriptor.js.map +1 -1
  48. package/dist/src/lib/credentials-store.d.ts +19 -0
  49. package/dist/src/lib/credentials-store.js +66 -2
  50. package/dist/src/lib/credentials-store.js.map +1 -1
  51. package/dist/src/lib/db-codegen/dbTypeIR.d.ts +2 -0
  52. package/dist/src/lib/db-codegen/dbTypeIR.js +3 -1
  53. package/dist/src/lib/db-codegen/dbTypeIR.js.map +1 -1
  54. package/dist/src/lib/db-type-records.d.ts +20 -1
  55. package/dist/src/lib/db-type-records.js +17 -4
  56. package/dist/src/lib/db-type-records.js.map +1 -1
  57. package/dist/src/lib/db3-export.d.ts +43 -8
  58. package/dist/src/lib/db3-export.js +133 -13
  59. package/dist/src/lib/db3-export.js.map +1 -1
  60. package/dist/src/lib/db3-json-fields.d.ts +49 -0
  61. package/dist/src/lib/db3-json-fields.js +195 -0
  62. package/dist/src/lib/db3-json-fields.js.map +1 -0
  63. package/dist/src/lib/db3-type-archive.d.ts +59 -0
  64. package/dist/src/lib/db3-type-archive.js +95 -0
  65. package/dist/src/lib/db3-type-archive.js.map +1 -0
  66. package/dist/src/lib/db3-type-models.d.ts +15 -1
  67. package/dist/src/lib/db3-type-models.js +147 -16
  68. package/dist/src/lib/db3-type-models.js.map +1 -1
  69. package/dist/src/lib/document-export-record-log.d.ts +7 -0
  70. package/dist/src/lib/document-export-record-log.js +9 -0
  71. package/dist/src/lib/document-export-record-log.js.map +1 -1
  72. package/dist/src/lib/document-ingest-artifact.d.ts +6 -0
  73. package/dist/src/lib/document-ingest-artifact.js +20 -1
  74. package/dist/src/lib/document-ingest-artifact.js.map +1 -1
  75. package/dist/src/lib/function-authorize-view.d.ts +9 -0
  76. package/dist/src/lib/function-authorize-view.js +22 -0
  77. package/dist/src/lib/function-authorize-view.js.map +1 -1
  78. package/dist/src/lib/function-collect.d.ts +22 -0
  79. package/dist/src/lib/function-collect.js +120 -1
  80. package/dist/src/lib/function-collect.js.map +1 -1
  81. package/dist/src/lib/function-db-types.js +31 -2
  82. package/dist/src/lib/function-db-types.js.map +1 -1
  83. package/dist/src/lib/function-grants-preflight.d.ts +99 -0
  84. package/dist/src/lib/function-grants-preflight.js +154 -2
  85. package/dist/src/lib/function-grants-preflight.js.map +1 -1
  86. package/dist/src/lib/function-lint.d.ts +29 -1
  87. package/dist/src/lib/function-lint.js +208 -0
  88. package/dist/src/lib/function-lint.js.map +1 -1
  89. package/dist/src/lib/function-sync.d.ts +11 -0
  90. package/dist/src/lib/function-sync.js +40 -2
  91. package/dist/src/lib/function-sync.js.map +1 -1
  92. package/dist/src/lib/generated-command-status.js +41 -8
  93. package/dist/src/lib/generated-command-status.js.map +1 -1
  94. package/dist/src/lib/generated-config-surfaces.d.ts +276 -9
  95. package/dist/src/lib/generated-config-surfaces.js +791 -24
  96. package/dist/src/lib/generated-config-surfaces.js.map +1 -1
  97. package/dist/src/lib/generated-sdk-types.d.ts +1 -1
  98. package/dist/src/lib/generated-sdk-types.js +1 -1
  99. package/dist/src/lib/generated-sdk-types.js.map +1 -1
  100. package/dist/src/lib/hosting-trust-step.d.ts +67 -0
  101. package/dist/src/lib/hosting-trust-step.js +279 -0
  102. package/dist/src/lib/hosting-trust-step.js.map +1 -0
  103. package/dist/src/lib/hosting-trust.d.ts +77 -0
  104. package/dist/src/lib/hosting-trust.js +194 -0
  105. package/dist/src/lib/hosting-trust.js.map +1 -0
  106. package/dist/src/lib/primitive-declaration.js +89 -10
  107. package/dist/src/lib/primitive-declaration.js.map +1 -1
  108. package/dist/src/lib/refresh-admin-credentials.d.ts +34 -4
  109. package/dist/src/lib/refresh-admin-credentials.js +85 -29
  110. package/dist/src/lib/refresh-admin-credentials.js.map +1 -1
  111. package/dist/src/lib/refresh-stored-login.d.ts +85 -0
  112. package/dist/src/lib/refresh-stored-login.js +233 -0
  113. package/dist/src/lib/refresh-stored-login.js.map +1 -0
  114. package/dist/src/lib/row-field-rename.d.ts +18 -0
  115. package/dist/src/lib/row-field-rename.js +32 -0
  116. package/dist/src/lib/row-field-rename.js.map +1 -0
  117. package/dist/src/lib/schema-codegen/generated-field-grammar.d.ts +13 -2
  118. package/dist/src/lib/schema-codegen/generated-field-grammar.js +24 -1
  119. package/dist/src/lib/schema-codegen/generated-field-grammar.js.map +1 -1
  120. package/dist/src/lib/schema-defs-module.d.ts +29 -0
  121. package/dist/src/lib/schema-defs-module.js +103 -0
  122. package/dist/src/lib/schema-defs-module.js.map +1 -0
  123. package/dist/src/lib/swift-codegen/sharedGenerator.d.ts +6 -0
  124. package/dist/src/lib/swift-codegen/sharedGenerator.js +74 -0
  125. package/dist/src/lib/swift-codegen/sharedGenerator.js.map +1 -1
  126. package/dist/src/lib/toml-list-edit.d.ts +33 -0
  127. package/dist/src/lib/toml-list-edit.js +481 -0
  128. package/dist/src/lib/toml-list-edit.js.map +1 -0
  129. package/dist/src/lib/toml-scalar-edit.d.ts +9 -0
  130. package/dist/src/lib/toml-scalar-edit.js +67 -1
  131. package/dist/src/lib/toml-scalar-edit.js.map +1 -1
  132. package/dist/src/lib/usage-meters.d.ts +16 -0
  133. package/dist/src/lib/usage-meters.js +52 -0
  134. package/dist/src/lib/usage-meters.js.map +1 -0
  135. package/package.json +2 -2
@@ -41,6 +41,16 @@ export interface FunctionVersionInputFields {
41
41
  input?: string[] | null;
42
42
  /** #5840 — whether this version opens to signed-out callers. */
43
43
  signedOut?: boolean;
44
+ /**
45
+ * #5844 — the version's `[function] public` options, as push stored them;
46
+ * `null` when it stores none.
47
+ */
48
+ publicOptions?: {
49
+ cacheSeconds?: number;
50
+ cors?: "*";
51
+ turnstile?: true;
52
+ rate?: "low" | "medium" | "high";
53
+ } | null;
44
54
  }
45
55
  /**
46
56
  * The live version's `authorize` flag and `input` list as the function get
@@ -325,6 +335,15 @@ export interface RateCounterState {
325
335
  key: string;
326
336
  counters: RateCounterWindow[];
327
337
  }
338
+ /** A single-use token's one use, as `GET /admin/api/apps/:appId/spent-tokens/:tokenId` answers it. */
339
+ export interface SpentTokenState {
340
+ tokenId: string;
341
+ /** What kind of token it is, e.g. `"db3-blob-upload"`. */
342
+ purpose: string;
343
+ usedAt: string;
344
+ /** The token's expiry; the row may be removed after it. */
345
+ expiresAt: string | null;
346
+ }
328
347
  /** The active user properties schema, as `GET users/properties` answers it. */
329
348
  export interface UserPropertiesActive {
330
349
  version: number;
@@ -1381,6 +1400,21 @@ export interface DatabaseBatchOperation {
1381
1400
  */
1382
1401
  condition?: Record<string, any>;
1383
1402
  }
1403
+ /** One place in an app's configuration that names a secret key (#5845). */
1404
+ export interface AppSecretReference {
1405
+ kind: "function-capability" | "cel-rule" | "integration" | "webhook-trigger" | "google-client";
1406
+ id: string;
1407
+ name: string;
1408
+ field: string;
1409
+ }
1410
+ /** What `GET …/secrets/by-key/{key}/references` answers (#5845). */
1411
+ export interface AppSecretReferences {
1412
+ key: string;
1413
+ reserved: boolean;
1414
+ stored: boolean;
1415
+ references: AppSecretReference[];
1416
+ truncated: boolean;
1417
+ }
1384
1418
  export declare class ApiClient {
1385
1419
  /**
1386
1420
  * Loaded on first use (`ensureAuthenticated`), never in a constructor.
@@ -1403,6 +1437,8 @@ export declare class ApiClient {
1403
1437
  private ensureAuthenticated;
1404
1438
  private refreshToken;
1405
1439
  request<T = any>(path: string, options?: RequestInit): Promise<T>;
1440
+ /** The HTTP status of the last request `request` answered without throwing. */
1441
+ private lastStatus;
1406
1442
  /**
1407
1443
  * Whether a 403 should be retried with the stored step-up: it names
1408
1444
  * `admin` among the missing scopes, or it is a protected app's refusal of
@@ -1655,6 +1691,8 @@ export declare class ApiClient {
1655
1691
  getUserWalk(appId: string, runId: string): Promise<UserWalkAnswer>;
1656
1692
  /** A rate counter's state by key (`GET /admin/api/apps/:appId/rate-counters/:key`). */
1657
1693
  getRateCounter(appId: string, key: string): Promise<RateCounterState>;
1694
+ /** A spent token of the app by id (`GET /admin/api/apps/:appId/spent-tokens/:tokenId`); 404 when it has not been used. */
1695
+ getSpentToken(appId: string, tokenId: string): Promise<SpentTokenState>;
1658
1696
  /** Stop a users walk (`POST /admin/api/apps/:appId/users/walks/:runId/terminate`); batches in flight finish. */
1659
1697
  terminateUserWalk(appId: string, runId: string): Promise<UserWalkAnswer & {
1660
1698
  terminated: boolean;
@@ -1833,6 +1871,25 @@ export declare class ApiClient {
1833
1871
  * its `inviteToken` (the bearer credential an accept link carries) and its
1834
1872
  * `status`. Readable by an app admin/owner or the inviter.
1835
1873
  */
1874
+ /**
1875
+ * What an invitation shows before anyone signs in (#5848), by its token.
1876
+ * The route reads no credential.
1877
+ */
1878
+ previewInvitation(appId: string, inviteToken: string): Promise<{
1879
+ appName: string;
1880
+ appIconUrl: string | null;
1881
+ inviterName: string | null;
1882
+ role: string;
1883
+ shared: Array<{
1884
+ kind: "db3" | "group" | "collection";
1885
+ title: string;
1886
+ level: string;
1887
+ }>;
1888
+ sharedTruncated: boolean;
1889
+ maskedEmail: string;
1890
+ status: "pending" | "expired" | "accepted";
1891
+ expiresAt: string | null;
1892
+ }>;
1836
1893
  getInvitation(appId: string, invitationId: string): Promise<{
1837
1894
  invitationId: string;
1838
1895
  email: string;
@@ -1929,6 +1986,12 @@ export declare class ApiClient {
1929
1986
  summary?: string;
1930
1987
  }): Promise<any>;
1931
1988
  deleteAppSecret(appId: string, secretId: string): Promise<any>;
1989
+ /**
1990
+ * What in the app's configuration names a secret key (#5845, beta): `{ key,
1991
+ * reserved, stored, references: [{ kind, id, name, field }], truncated }`.
1992
+ * Answers for any key, stored or not; never a value.
1993
+ */
1994
+ getAppSecretReferences(appId: string, key: string): Promise<AppSecretReferences>;
1932
1995
  listAppConfigVars(appId: string): Promise<any[]>;
1933
1996
  upsertAppConfigVar(appId: string, key: string, payload: {
1934
1997
  value: string;
@@ -3601,6 +3664,21 @@ export declare class ApiClient {
3601
3664
  record: unknown;
3602
3665
  values: Record<string, number>;
3603
3666
  }>;
3667
+ /**
3668
+ * `POST db3/:id/records/:model/clear` (#5994): empty one model in one
3669
+ * operation; `{ ok, model, rows, lsn, epoch, dropped, cost }`.
3670
+ */
3671
+ clearDb3Model(appId: string, db3Id: string, modelName: string, body?: {
3672
+ drop?: boolean;
3673
+ }): Promise<{
3674
+ ok: boolean;
3675
+ model: string;
3676
+ rows: number;
3677
+ lsn: number | null;
3678
+ epoch: number | null;
3679
+ dropped: boolean;
3680
+ cost?: unknown;
3681
+ }>;
3604
3682
  /** `GET db3/:id/sync` (#4799): `{ id, sync }`. */
3605
3683
  getDb3Sync(appId: string, db3Id: string): Promise<{
3606
3684
  id: string;
@@ -3623,6 +3701,89 @@ export declare class ApiClient {
3623
3701
  level: string | null;
3624
3702
  changed: boolean;
3625
3703
  }>;
3704
+ /**
3705
+ * `PUT db3/:id/public-access` (#5842): mark the db3 public at `reader`, or
3706
+ * clear it with null; `signedOutAccess` is the app's setting, which decides
3707
+ * whether the value is honoured yet.
3708
+ */
3709
+ setDb3PublicAccess(appId: string, db3Id: string, level: "reader" | null): Promise<{
3710
+ id: string;
3711
+ level: "reader" | null;
3712
+ changed: boolean;
3713
+ signedOutAccess: boolean;
3714
+ }>;
3715
+ /** `GET db3/:id/link-access`: `{ documentId, linkAccess, … }`, `linkAccess` null when off. */
3716
+ getDb3LinkAccess(appId: string, db3Id: string): Promise<{
3717
+ documentId: string;
3718
+ linkAccess: string | null;
3719
+ [key: string]: unknown;
3720
+ }>;
3721
+ /** `PUT db3/:id/link-access`: let anyone in the app with the id open the db3 at `level`. */
3722
+ setDb3LinkAccess(appId: string, db3Id: string, level: "reader" | "read-write"): Promise<any>;
3723
+ /** `DELETE db3/:id/link-access`: turn the db3's link access off. */
3724
+ clearDb3LinkAccess(appId: string, db3Id: string): Promise<any>;
3725
+ /** `GET db3/:id/permissions`: the db3's user grants, a bare array of `{ userId, email, name, permission, grantedAt }`. */
3726
+ listDb3Permissions(appId: string, db3Id: string): Promise<any[]>;
3727
+ /**
3728
+ * `PUT db3/:id/permissions`: grant one user, named by `userId` or `email`,
3729
+ * a level; `sendEmail` tells them, with `documentUrl` and `note` in the email.
3730
+ */
3731
+ grantDb3Permission(appId: string, db3Id: string, entry: {
3732
+ userId?: string;
3733
+ email?: string;
3734
+ permission: string;
3735
+ }, email?: {
3736
+ sendEmail?: boolean;
3737
+ documentUrl?: string;
3738
+ note?: string;
3739
+ }): Promise<any>;
3740
+ /** `DELETE db3/:id/permissions/:userId`, or `DELETE db3/:id/permissions?email=` for an email: revoke one user's grant. */
3741
+ revokeDb3Permission(appId: string, db3Id: string, target: {
3742
+ userId?: string;
3743
+ email?: string;
3744
+ }): Promise<any>;
3745
+ /** `GET db3/:id/group-permissions`: the db3's group grants, a bare array; `includeSystem` adds system groups'. */
3746
+ listDb3GroupPermissions(appId: string, db3Id: string, options?: {
3747
+ includeSystem?: boolean;
3748
+ }): Promise<any[]>;
3749
+ /** `POST db3/:id/group-permissions`: grant a group, named by its id, a level. */
3750
+ grantDb3GroupPermission(appId: string, db3Id: string, groupId: string, permission: string): Promise<any>;
3751
+ /** `DELETE db3/:id/group-permissions/:groupId`: revoke a group's grant. */
3752
+ revokeDb3GroupPermission(appId: string, db3Id: string, groupId: string): Promise<any>;
3753
+ /** `GET db3/:id/pending-invitations`: `{ items }`, the grants waiting for an address to join the app. */
3754
+ listDb3PendingInvitations(appId: string, db3Id: string): Promise<{
3755
+ items: any[];
3756
+ }>;
3757
+ /** `DELETE db3/:id/pending-invitations/:invitationId`: cancel a pending invitation's grants on this db3. */
3758
+ revokeDb3PendingInvitation(appId: string, db3Id: string, invitationId: string): Promise<any>;
3759
+ /** `GET db3/:id/access-requests`: the pending access requests, a bare array. */
3760
+ listDb3AccessRequests(appId: string, db3Id: string): Promise<any[]>;
3761
+ /**
3762
+ * `POST db3/:id/access-requests`: the signed-in caller asks for access.
3763
+ * `created` is true when the request is new (201) and false when the
3764
+ * caller's pending request was updated (200).
3765
+ */
3766
+ createDb3AccessRequest(appId: string, db3Id: string, body: {
3767
+ permission: string;
3768
+ message?: string;
3769
+ documentUrl?: string;
3770
+ reviewUrl?: string;
3771
+ sendEmail?: boolean;
3772
+ }): Promise<{
3773
+ answer: any;
3774
+ created: boolean;
3775
+ }>;
3776
+ /** `POST db3/:id/access-requests/:requestId/approve`: grant the requested level, or `permission`. */
3777
+ approveDb3AccessRequest(appId: string, db3Id: string, requestId: string, body?: {
3778
+ permission?: string;
3779
+ documentUrl?: string;
3780
+ }): Promise<any>;
3781
+ /** `POST db3/:id/access-requests/:requestId/deny`: deny the request. */
3782
+ denyDb3AccessRequest(appId: string, db3Id: string, requestId: string, body?: {
3783
+ documentUrl?: string;
3784
+ }): Promise<any>;
3785
+ /** `POST db3/:id/validate-access` with `{ userId }`: a named user's effective access to the db3. */
3786
+ validateDb3AccessForUser(appId: string, db3Id: string, userId: string): Promise<any>;
3626
3787
  /** One custodian's db3s through the admin API (#4800): `custodian` is `app` or `user:<userId>`. */
3627
3788
  listDb3ByCustodian(appId: string, custodian: string, params?: {
3628
3789
  limit?: number;
@@ -3681,6 +3842,10 @@ export declare class ApiClient {
3681
3842
  schema?: string | null;
3682
3843
  metadataManifest?: any;
3683
3844
  expectedModifiedAt?: string;
3845
+ /** #6020 — `true` archives the type, `false` or `null` unarchives it; omitted keeps it. */
3846
+ archived?: boolean | null;
3847
+ /** #5998 — who creates db3s of the type: `"admins"`, or `"members"`/`null` for every member; omitted keeps it. */
3848
+ create?: "admins" | "members" | null;
3684
3849
  }, options?: {
3685
3850
  dryRun?: boolean;
3686
3851
  allowFieldRemoval?: boolean;
@@ -5,7 +5,8 @@ import { pinRefusalHint } from "./pin-refusal-hint.js";
5
5
  import { fetchWithTLS } from "./fetch.js";
6
6
  import { CLI_VERSION_HEADER, cliVersionHeaderValue } from "./cli-version.js";
7
7
  import { paginateAll, normalizeCliListEnvelope } from "./paginate.js";
8
- import { RefreshError, refreshAdminCredentials, } from "./refresh-admin-credentials.js";
8
+ import { RefreshError } from "./refresh-admin-credentials.js";
9
+ import { refreshFromStoredLogin } from "./refresh-stored-login.js";
9
10
  /** The `X-Primitive-CLI-Version` value, read from the package file once per process. */
10
11
  let cliVersion;
11
12
  /**
@@ -170,6 +171,11 @@ export class TomlParseError extends ApiError {
170
171
  return typeof d?.column === "number" ? d.column : undefined;
171
172
  }
172
173
  }
174
+ /**
175
+ * The query a db3 record call carries so a renamed field is answered under
176
+ * its current name, the name the type file gives it.
177
+ */
178
+ const DB3_CURRENT_NAMES = "?names=current";
173
179
  export class ApiClient {
174
180
  /**
175
181
  * Loaded on first use (`ensureAuthenticated`), never in a constructor.
@@ -215,9 +221,9 @@ export class ApiClient {
215
221
  throw new ApiError("Not logged in. Run 'primitive login' first.", 401);
216
222
  }
217
223
  try {
218
- const updated = await refreshAdminCredentials(this.credentials);
219
- this.credentials = updated;
220
- saveCredentials(this.credentials);
224
+ // #5926 — refresh from the login stored now, not the copy loaded at
225
+ // start: another process may have rotated its refresh token.
226
+ this.credentials = await refreshFromStoredLogin(this.credentials);
221
227
  }
222
228
  catch (err) {
223
229
  if (err instanceof RefreshError) {
@@ -271,6 +277,7 @@ export class ApiClient {
271
277
  if (response.status === 403 && this.stepUpApplies(response, text, path)) {
272
278
  const retried = await send(credentials.stepUp.accessToken);
273
279
  if (retried.response.ok) {
280
+ this.lastStatus = retried.response.status;
274
281
  return answered(retried.text);
275
282
  }
276
283
  if (retried.response.status === 401) {
@@ -283,8 +290,11 @@ export class ApiClient {
283
290
  if (!response.ok) {
284
291
  throw this.responseError(response, text, path);
285
292
  }
293
+ this.lastStatus = response.status;
286
294
  return answered(text);
287
295
  }
296
+ /** The HTTP status of the last request `request` answered without throwing. */
297
+ lastStatus;
288
298
  /**
289
299
  * Whether a 403 should be retried with the stored step-up: it names
290
300
  * `admin` among the missing scopes, or it is a protected app's refusal of
@@ -669,6 +679,10 @@ export class ApiClient {
669
679
  async getRateCounter(appId, key) {
670
680
  return this.get(`/admin/api/apps/${appId}/rate-counters/${encodeURIComponent(key)}`);
671
681
  }
682
+ /** A spent token of the app by id (`GET /admin/api/apps/:appId/spent-tokens/:tokenId`); 404 when it has not been used. */
683
+ async getSpentToken(appId, tokenId) {
684
+ return this.get(`/admin/api/apps/${appId}/spent-tokens/${encodeURIComponent(tokenId)}`);
685
+ }
672
686
  /** Stop a users walk (`POST /admin/api/apps/:appId/users/walks/:runId/terminate`); batches in flight finish. */
673
687
  async terminateUserWalk(appId, runId) {
674
688
  return this.post(`/admin/api/apps/${appId}/users/walks/${encodeURIComponent(runId)}/terminate`, {});
@@ -866,6 +880,13 @@ export class ApiClient {
866
880
  * its `inviteToken` (the bearer credential an accept link carries) and its
867
881
  * `status`. Readable by an app admin/owner or the inviter.
868
882
  */
883
+ /**
884
+ * What an invitation shows before anyone signs in (#5848), by its token.
885
+ * The route reads no credential.
886
+ */
887
+ async previewInvitation(appId, inviteToken) {
888
+ return this.get(`/app/${appId}/api/invitations/preview`, { inviteToken });
889
+ }
869
890
  async getInvitation(appId, invitationId) {
870
891
  return this.get(`/app/${appId}/api/invitations/${encodeURIComponent(invitationId)}`);
871
892
  }
@@ -976,6 +997,14 @@ export class ApiClient {
976
997
  async deleteAppSecret(appId, secretId) {
977
998
  return this.delete(`/admin/api/apps/${appId}/secrets/${secretId}`);
978
999
  }
1000
+ /**
1001
+ * What in the app's configuration names a secret key (#5845, beta): `{ key,
1002
+ * reserved, stored, references: [{ kind, id, name, field }], truncated }`.
1003
+ * Answers for any key, stored or not; never a value.
1004
+ */
1005
+ async getAppSecretReferences(appId, key) {
1006
+ return this.get(`/admin/api/apps/${appId}/secrets/by-key/${encodeURIComponent(key)}/references`);
1007
+ }
979
1008
  // ============================================
980
1009
  // APP CONFIG VARS (issue #1364 — non-secret twin of secrets)
981
1010
  // ============================================
@@ -2874,6 +2903,8 @@ export class ApiClient {
2874
2903
  query.limit = queryOptions.limit;
2875
2904
  if (queryOptions?.cursor)
2876
2905
  query.cursor = queryOptions.cursor;
2906
+ // #6022 — the CLI prints a renamed field under its current name.
2907
+ query.names = "current";
2877
2908
  const raw = await this.get(`${this.db3Path(appId, db3Id)}/records/${encodeURIComponent(modelName)}`, query);
2878
2909
  return normalizeCliListEnvelope(raw);
2879
2910
  }
@@ -2882,11 +2913,12 @@ export class ApiClient {
2882
2913
  const query = {};
2883
2914
  if (queryOptions?.filter)
2884
2915
  query.filter = JSON.stringify(queryOptions.filter);
2916
+ query.names = "current";
2885
2917
  return this.get(`${this.db3Path(appId, db3Id)}/records/${encodeURIComponent(modelName)}/count`, query);
2886
2918
  }
2887
2919
  /** The db3 mount of {@link aggregateDocumentRecords}: `POST db3/:id/records/:model/aggregate`. */
2888
2920
  async aggregateDb3Records(appId, db3Id, modelName, options) {
2889
- return this.post(`${this.db3Path(appId, db3Id)}/records/${encodeURIComponent(modelName)}/aggregate`, { options });
2921
+ return this.post(`${this.db3Path(appId, db3Id)}/records/${encodeURIComponent(modelName)}/aggregate${DB3_CURRENT_NAMES}`, { options });
2890
2922
  }
2891
2923
  /**
2892
2924
  * `POST db3/:id/records/:model/explain` (#5240): run a query, count or
@@ -2898,11 +2930,11 @@ export class ApiClient {
2898
2930
  }
2899
2931
  /** The db3 mount of {@link saveDocumentRecord}: `POST db3/:id/records/:model`. */
2900
2932
  async saveDb3Record(appId, db3Id, modelName, body) {
2901
- return this.post(`${this.db3Path(appId, db3Id)}/records/${encodeURIComponent(modelName)}`, body);
2933
+ return this.post(`${this.db3Path(appId, db3Id)}/records/${encodeURIComponent(modelName)}${DB3_CURRENT_NAMES}`, body);
2902
2934
  }
2903
2935
  /** The db3 mount of {@link patchDocumentRecord}: `PATCH db3/:id/records/:model/:recordId`. */
2904
2936
  async patchDb3Record(appId, db3Id, modelName, recordId, body) {
2905
- return this.patch(`${this.db3Path(appId, db3Id)}/records/${encodeURIComponent(modelName)}/${encodeURIComponent(recordId)}`, body);
2937
+ return this.patch(`${this.db3Path(appId, db3Id)}/records/${encodeURIComponent(modelName)}/${encodeURIComponent(recordId)}${DB3_CURRENT_NAMES}`, body);
2906
2938
  }
2907
2939
  /** The db3 mount of {@link deleteDocumentRecord}: `DELETE db3/:id/records/:model/:recordId`. */
2908
2940
  async deleteDb3Record(appId, db3Id, modelName, recordId) {
@@ -2910,7 +2942,7 @@ export class ApiClient {
2910
2942
  }
2911
2943
  /** The db3 mount of {@link batchDocumentRecords}: `POST db3/:id/records/batch`. */
2912
2944
  async batchDb3Records(appId, db3Id, operations) {
2913
- return this.post(`${this.db3Path(appId, db3Id)}/records/batch`, { operations });
2945
+ return this.post(`${this.db3Path(appId, db3Id)}/records/batch${DB3_CURRENT_NAMES}`, { operations });
2914
2946
  }
2915
2947
  /**
2916
2948
  * Several reads of a db3 in one request (#5243): `POST db3/:id/records/batch-read`,
@@ -2918,7 +2950,7 @@ export class ApiClient {
2918
2950
  * answers a refused read in its place rather than refusing the request.
2919
2951
  */
2920
2952
  async batchReadDb3Records(appId, db3Id, operations, options = {}) {
2921
- return this.post(`${this.db3Path(appId, db3Id)}/records/batch-read`, {
2953
+ return this.post(`${this.db3Path(appId, db3Id)}/records/batch-read${DB3_CURRENT_NAMES}`, {
2922
2954
  operations,
2923
2955
  ...(options.atomic === false ? { atomic: false } : {}),
2924
2956
  });
@@ -3034,7 +3066,14 @@ export class ApiClient {
3034
3066
  * `fields` to the record's field, answering `{ record, values }`.
3035
3067
  */
3036
3068
  async incrementDb3Record(appId, db3Id, modelName, recordId, body) {
3037
- return this.post(`${this.db3Path(appId, db3Id)}/records/${encodeURIComponent(modelName)}/${encodeURIComponent(recordId)}/increment`, body);
3069
+ return this.post(`${this.db3Path(appId, db3Id)}/records/${encodeURIComponent(modelName)}/${encodeURIComponent(recordId)}/increment${DB3_CURRENT_NAMES}`, body);
3070
+ }
3071
+ /**
3072
+ * `POST db3/:id/records/:model/clear` (#5994): empty one model in one
3073
+ * operation; `{ ok, model, rows, lsn, epoch, dropped, cost }`.
3074
+ */
3075
+ async clearDb3Model(appId, db3Id, modelName, body = {}) {
3076
+ return this.post(`${this.db3Path(appId, db3Id)}/records/${encodeURIComponent(modelName)}/clear`, body);
3038
3077
  }
3039
3078
  /** `GET db3/:id/sync` (#4799): `{ id, sync }`. */
3040
3079
  async getDb3Sync(appId, db3Id) {
@@ -3052,6 +3091,91 @@ export class ApiClient {
3052
3091
  async setDb3AppAccess(appId, db3Id, level) {
3053
3092
  return this.put(`${this.db3Path(appId, db3Id)}/app-access`, { level });
3054
3093
  }
3094
+ /**
3095
+ * `PUT db3/:id/public-access` (#5842): mark the db3 public at `reader`, or
3096
+ * clear it with null; `signedOutAccess` is the app's setting, which decides
3097
+ * whether the value is honoured yet.
3098
+ */
3099
+ async setDb3PublicAccess(appId, db3Id, level) {
3100
+ return this.put(`${this.db3Path(appId, db3Id)}/public-access`, { level });
3101
+ }
3102
+ /** `GET db3/:id/link-access`: `{ documentId, linkAccess, … }`, `linkAccess` null when off. */
3103
+ async getDb3LinkAccess(appId, db3Id) {
3104
+ return this.get(`${this.db3Path(appId, db3Id)}/link-access`);
3105
+ }
3106
+ /** `PUT db3/:id/link-access`: let anyone in the app with the id open the db3 at `level`. */
3107
+ async setDb3LinkAccess(appId, db3Id, level) {
3108
+ return this.put(`${this.db3Path(appId, db3Id)}/link-access`, { level });
3109
+ }
3110
+ /** `DELETE db3/:id/link-access`: turn the db3's link access off. */
3111
+ async clearDb3LinkAccess(appId, db3Id) {
3112
+ return this.delete(`${this.db3Path(appId, db3Id)}/link-access`);
3113
+ }
3114
+ /** `GET db3/:id/permissions`: the db3's user grants, a bare array of `{ userId, email, name, permission, grantedAt }`. */
3115
+ async listDb3Permissions(appId, db3Id) {
3116
+ return this.get(`${this.db3Path(appId, db3Id)}/permissions`);
3117
+ }
3118
+ /**
3119
+ * `PUT db3/:id/permissions`: grant one user, named by `userId` or `email`,
3120
+ * a level; `sendEmail` tells them, with `documentUrl` and `note` in the email.
3121
+ */
3122
+ async grantDb3Permission(appId, db3Id, entry, email) {
3123
+ return this.put(`${this.db3Path(appId, db3Id)}/permissions`, { permissions: [entry], ...(email ?? {}) });
3124
+ }
3125
+ /** `DELETE db3/:id/permissions/:userId`, or `DELETE db3/:id/permissions?email=` for an email: revoke one user's grant. */
3126
+ async revokeDb3Permission(appId, db3Id, target) {
3127
+ if (target.email) {
3128
+ return this.delete(`${this.db3Path(appId, db3Id)}/permissions?email=${encodeURIComponent(target.email)}`);
3129
+ }
3130
+ if (!target.userId)
3131
+ throw new Error("revokeDb3Permission: userId or email is required");
3132
+ return this.delete(`${this.db3Path(appId, db3Id)}/permissions/${encodeURIComponent(target.userId)}`);
3133
+ }
3134
+ /** `GET db3/:id/group-permissions`: the db3's group grants, a bare array; `includeSystem` adds system groups'. */
3135
+ async listDb3GroupPermissions(appId, db3Id, options) {
3136
+ return this.get(`${this.db3Path(appId, db3Id)}/group-permissions`, options?.includeSystem ? { includeSystem: "true" } : undefined);
3137
+ }
3138
+ /** `POST db3/:id/group-permissions`: grant a group, named by its id, a level. */
3139
+ async grantDb3GroupPermission(appId, db3Id, groupId, permission) {
3140
+ return this.post(`${this.db3Path(appId, db3Id)}/group-permissions`, { groupId, permission });
3141
+ }
3142
+ /** `DELETE db3/:id/group-permissions/:groupId`: revoke a group's grant. */
3143
+ async revokeDb3GroupPermission(appId, db3Id, groupId) {
3144
+ return this.delete(`${this.db3Path(appId, db3Id)}/group-permissions/${encodeURIComponent(groupId)}`);
3145
+ }
3146
+ /** `GET db3/:id/pending-invitations`: `{ items }`, the grants waiting for an address to join the app. */
3147
+ async listDb3PendingInvitations(appId, db3Id) {
3148
+ return this.get(`${this.db3Path(appId, db3Id)}/pending-invitations`);
3149
+ }
3150
+ /** `DELETE db3/:id/pending-invitations/:invitationId`: cancel a pending invitation's grants on this db3. */
3151
+ async revokeDb3PendingInvitation(appId, db3Id, invitationId) {
3152
+ return this.delete(`${this.db3Path(appId, db3Id)}/pending-invitations/${encodeURIComponent(invitationId)}`);
3153
+ }
3154
+ /** `GET db3/:id/access-requests`: the pending access requests, a bare array. */
3155
+ async listDb3AccessRequests(appId, db3Id) {
3156
+ return this.get(`${this.db3Path(appId, db3Id)}/access-requests`);
3157
+ }
3158
+ /**
3159
+ * `POST db3/:id/access-requests`: the signed-in caller asks for access.
3160
+ * `created` is true when the request is new (201) and false when the
3161
+ * caller's pending request was updated (200).
3162
+ */
3163
+ async createDb3AccessRequest(appId, db3Id, body) {
3164
+ const answer = await this.post(`${this.db3Path(appId, db3Id)}/access-requests`, body);
3165
+ return { answer, created: this.lastStatus === 201 };
3166
+ }
3167
+ /** `POST db3/:id/access-requests/:requestId/approve`: grant the requested level, or `permission`. */
3168
+ async approveDb3AccessRequest(appId, db3Id, requestId, body = {}) {
3169
+ return this.post(`${this.db3Path(appId, db3Id)}/access-requests/${encodeURIComponent(requestId)}/approve`, body);
3170
+ }
3171
+ /** `POST db3/:id/access-requests/:requestId/deny`: deny the request. */
3172
+ async denyDb3AccessRequest(appId, db3Id, requestId, body = {}) {
3173
+ return this.post(`${this.db3Path(appId, db3Id)}/access-requests/${encodeURIComponent(requestId)}/deny`, body);
3174
+ }
3175
+ /** `POST db3/:id/validate-access` with `{ userId }`: a named user's effective access to the db3. */
3176
+ async validateDb3AccessForUser(appId, db3Id, userId) {
3177
+ return this.post(`${this.db3Path(appId, db3Id)}/validate-access`, { userId });
3178
+ }
3055
3179
  /** One custodian's db3s through the admin API (#4800): `custodian` is `app` or `user:<userId>`. */
3056
3180
  async listDb3ByCustodian(appId, custodian, params) {
3057
3181
  const result = await this.get(`/admin/api/apps/${appId}/db3`, { custodian, ...(params ?? {}) });