@bedrock-rbx/ocale 0.3.4 → 0.4.0

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 (85) hide show
  1. package/README.md +9 -5
  2. package/dist/badge-cost-mismatch-DrlvhlQc.mjs +47 -0
  3. package/dist/badge-cost-mismatch-DrlvhlQc.mjs.map +1 -0
  4. package/dist/badges.d.mts +228 -184
  5. package/dist/badges.d.mts.map +1 -1
  6. package/dist/badges.mjs +176 -18
  7. package/dist/badges.mjs.map +1 -1
  8. package/dist/capacity-admission-hycCFkTo.d.mts +355 -0
  9. package/dist/capacity-admission-hycCFkTo.d.mts.map +1 -0
  10. package/dist/{data.generated-B2ceLfSn.d.mts → data.generated-D_vpa5-g.d.mts} +23 -23
  11. package/dist/data.generated-D_vpa5-g.d.mts.map +1 -0
  12. package/dist/developer-products.d.mts +181 -186
  13. package/dist/developer-products.d.mts.map +1 -1
  14. package/dist/developer-products.mjs +24 -24
  15. package/dist/developer-products.mjs.map +1 -1
  16. package/dist/game-passes.d.mts +206 -203
  17. package/dist/game-passes.d.mts.map +1 -1
  18. package/dist/game-passes.mjs +26 -21
  19. package/dist/game-passes.mjs.map +1 -1
  20. package/dist/index.d.mts +905 -343
  21. package/dist/index.d.mts.map +1 -1
  22. package/dist/index.mjs +325 -10
  23. package/dist/index.mjs.map +1 -1
  24. package/dist/locales.d.mts +30 -2
  25. package/dist/locales.d.mts.map +1 -0
  26. package/dist/locales.mjs +24 -1
  27. package/dist/locales.mjs.map +1 -1
  28. package/dist/luau-execution.d.mts +154 -151
  29. package/dist/luau-execution.d.mts.map +1 -1
  30. package/dist/luau-execution.mjs +11 -8
  31. package/dist/luau-execution.mjs.map +1 -1
  32. package/dist/{network-error-DR9FX5hb.mjs → network-error-iVSng5MT.mjs} +44 -6
  33. package/dist/network-error-iVSng5MT.mjs.map +1 -0
  34. package/dist/places.d.mts +204 -180
  35. package/dist/places.d.mts.map +1 -1
  36. package/dist/places.mjs +66 -20
  37. package/dist/places.mjs.map +1 -1
  38. package/dist/{poll-timeout-3PXLsabj.mjs → poll-timeout-DzztDymd.mjs} +2 -2
  39. package/dist/{poll-timeout-3PXLsabj.mjs.map → poll-timeout-DzztDymd.mjs.map} +1 -1
  40. package/dist/{polling-helpers-CoVhsC33.mjs → polling-helpers-DfF5dspc.mjs} +249 -83
  41. package/dist/polling-helpers-DfF5dspc.mjs.map +1 -0
  42. package/dist/{price-information-B0tkOoAX.mjs → price-information-DEkEQ8Pq.mjs} +2 -2
  43. package/dist/{price-information-B0tkOoAX.mjs.map → price-information-DEkEQ8Pq.mjs.map} +1 -1
  44. package/dist/resource-client-BCKukheG.d.mts +168 -0
  45. package/dist/resource-client-BCKukheG.d.mts.map +1 -0
  46. package/dist/{resource-client-rqTMkBeR.mjs → resource-client-CaIVr-go.mjs} +586 -158
  47. package/dist/resource-client-CaIVr-go.mjs.map +1 -0
  48. package/dist/retry-C2oHesDx.d.mts +229 -0
  49. package/dist/retry-C2oHesDx.d.mts.map +1 -0
  50. package/dist/{retry-BlX4tUnT.mjs → retry-CMRDvAR4.mjs} +278 -18
  51. package/dist/retry-CMRDvAR4.mjs.map +1 -0
  52. package/dist/storage.d.mts +333 -334
  53. package/dist/storage.d.mts.map +1 -1
  54. package/dist/storage.mjs +29 -22
  55. package/dist/storage.mjs.map +1 -1
  56. package/dist/testing.d.mts +347 -360
  57. package/dist/testing.d.mts.map +1 -1
  58. package/dist/testing.mjs +3 -4
  59. package/dist/testing.mjs.map +1 -1
  60. package/dist/types-CdMr_J1M.d.mts +509 -0
  61. package/dist/types-CdMr_J1M.d.mts.map +1 -0
  62. package/dist/universes.d.mts +619 -422
  63. package/dist/universes.d.mts.map +1 -1
  64. package/dist/universes.mjs +421 -48
  65. package/dist/universes.mjs.map +1 -1
  66. package/dist/{validation-B_Zs1So2.mjs → validation-964VNlbp.mjs} +2 -2
  67. package/dist/{validation-B_Zs1So2.mjs.map → validation-964VNlbp.mjs.map} +1 -1
  68. package/dist/wire-DJqupefn.d.mts +41 -0
  69. package/dist/wire-DJqupefn.d.mts.map +1 -0
  70. package/package.json +14 -14
  71. package/dist/capacity-admission-IDO3fcUC.d.mts +0 -369
  72. package/dist/capacity-admission-IDO3fcUC.d.mts.map +0 -1
  73. package/dist/data.generated-B2ceLfSn.d.mts.map +0 -1
  74. package/dist/network-error-DR9FX5hb.mjs.map +0 -1
  75. package/dist/polling-helpers-CoVhsC33.mjs.map +0 -1
  76. package/dist/resource-client-B6NeFXUv.d.mts +0 -164
  77. package/dist/resource-client-B6NeFXUv.d.mts.map +0 -1
  78. package/dist/resource-client-rqTMkBeR.mjs.map +0 -1
  79. package/dist/retry-BlX4tUnT.mjs.map +0 -1
  80. package/dist/retry-war_-9tb.d.mts +0 -373
  81. package/dist/retry-war_-9tb.d.mts.map +0 -1
  82. package/dist/types-CvYh4SPC.d.mts +0 -386
  83. package/dist/types-CvYh4SPC.d.mts.map +0 -1
  84. package/dist/wire-D3K-a-UP.d.mts +0 -37
  85. package/dist/wire-D3K-a-UP.d.mts.map +0 -1
package/README.md CHANGED
@@ -43,8 +43,8 @@ pnpm add @bedrock-rbx/ocale
43
43
 
44
44
  **Runtime:** Node >= 24.12 or Bun >= 1.3.
45
45
 
46
- **Authentication:** every client takes an `apiKey` at construction. Generate one
47
- at
46
+ **Authentication:** every client takes a `credential` at construction, for
47
+ example `{ kind: "apiKey", apiKey }`. Generate an API key at
48
48
  [Creator Hub > Credentials > API Keys](https://create.roblox.com/dashboard/credentials)
49
49
  and grant it the scopes for the operations you plan to call (each method's JSDoc
50
50
  lists its required scopes).
@@ -54,7 +54,9 @@ lists its required scopes).
54
54
  ```ts
55
55
  import { GamePassesClient } from "@bedrock-rbx/ocale/game-passes";
56
56
 
57
- const client = new GamePassesClient({ apiKey: "your-open-cloud-api-key" });
57
+ const client = new GamePassesClient({
58
+ credential: { apiKey: "your-open-cloud-api-key", kind: "apiKey" },
59
+ });
58
60
 
59
61
  const result = await client.get({
60
62
  gamePassId: "9876543210",
@@ -140,10 +142,12 @@ Client-level config is frozen on construction. Every method accepts an optional
140
142
  second `RequestOptions` argument that overrides config for a single call:
141
143
 
142
144
  ```ts
143
- const client = new GamePassesClient({ apiKey: "main-key" });
145
+ const client = new GamePassesClient({
146
+ credential: { apiKey: "main-key", kind: "apiKey" },
147
+ });
144
148
 
145
149
  const result = await client.create(parameters, {
146
- apiKey: "asset-upload-key", // different key for moderation safety
150
+ credential: { apiKey: "asset-upload-key", kind: "apiKey" }, // different key for moderation safety
147
151
  deadlineMs: Date.now() + 495_000,
148
152
  timeout: 60_000,
149
153
  });
@@ -0,0 +1,47 @@
1
+ import { s as OpenCloudError } from "./network-error-iVSng5MT.mjs";
2
+ //#region src/errors/badge-cost-mismatch.ts
3
+ /**
4
+ * Returned when Roblox refuses a badge create because its `expectedCost`
5
+ * differs from what the badge would actually cost (body error code `18`).
6
+ * Nothing is charged. A create sent with `expectedCost: 0` gets this once the
7
+ * universe has used its free badge quota for the day. The upstream `ApiError`
8
+ * is the `cause`.
9
+ *
10
+ * @since 0.4.0
11
+ *
12
+ * @example
13
+ *
14
+ * ```ts
15
+ * import { BadgeCostMismatchError } from "@bedrock-rbx/ocale";
16
+ *
17
+ * const error = new BadgeCostMismatchError(
18
+ * "Expected badge cost is different from the actual badge cost.",
19
+ * { code: "18", expectedCost: 0, statusCode: 403 },
20
+ * );
21
+ *
22
+ * // A free create was refused: the free badge quota is spent for today.
23
+ * expect(error.expectedCost).toBe(0);
24
+ * expect(error.statusCode).toBe(403);
25
+ * ```
26
+ */
27
+ var BadgeCostMismatchError = class extends OpenCloudError {
28
+ expectedCost;
29
+ name = "BadgeCostMismatchError";
30
+ statusCode;
31
+ /**
32
+ * Creates a new BadgeCostMismatchError.
33
+ *
34
+ * @param message - Human-readable error description.
35
+ * @param options - Error options including the cost the create expected
36
+ * and the HTTP status of the refusal.
37
+ */
38
+ constructor(message, options) {
39
+ super(message, options);
40
+ this.expectedCost = options.expectedCost;
41
+ this.statusCode = options.statusCode;
42
+ }
43
+ };
44
+ //#endregion
45
+ export { BadgeCostMismatchError as t };
46
+
47
+ //# sourceMappingURL=badge-cost-mismatch-DrlvhlQc.mjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"badge-cost-mismatch-DrlvhlQc.mjs","names":[],"sources":["../src/errors/badge-cost-mismatch.ts"],"sourcesContent":["import { OpenCloudError, type OpenCloudErrorOptions } from \"./base.ts\";\n\n/**\n * Options for constructing a {@link BadgeCostMismatchError}.\n *\n * @since 0.4.0\n */\nexport interface BadgeCostMismatchErrorOptions extends OpenCloudErrorOptions {\n\t/** The `expectedCost` the create sent, or `undefined` when it sent none. */\n\treadonly expectedCost: number | undefined;\n\t/** HTTP status code of the refusal. */\n\treadonly statusCode: number;\n}\n\n/**\n * Returned when Roblox refuses a badge create because its `expectedCost`\n * differs from what the badge would actually cost (body error code `18`).\n * Nothing is charged. A create sent with `expectedCost: 0` gets this once the\n * universe has used its free badge quota for the day. The upstream `ApiError`\n * is the `cause`.\n *\n * @since 0.4.0\n *\n * @example\n *\n * ```ts\n * import { BadgeCostMismatchError } from \"@bedrock-rbx/ocale\";\n *\n * const error = new BadgeCostMismatchError(\n * \"Expected badge cost is different from the actual badge cost.\",\n * { code: \"18\", expectedCost: 0, statusCode: 403 },\n * );\n *\n * // A free create was refused: the free badge quota is spent for today.\n * expect(error.expectedCost).toBe(0);\n * expect(error.statusCode).toBe(403);\n * ```\n */\nexport class BadgeCostMismatchError extends OpenCloudError {\n\tpublic readonly expectedCost: number | undefined;\n\tpublic override readonly name: string = \"BadgeCostMismatchError\";\n\tpublic readonly statusCode: number;\n\n\t/**\n\t * Creates a new BadgeCostMismatchError.\n\t *\n\t * @param message - Human-readable error description.\n\t * @param options - Error options including the cost the create expected\n\t * and the HTTP status of the refusal.\n\t */\n\tconstructor(message: string, options: BadgeCostMismatchErrorOptions) {\n\t\tsuper(message, options);\n\t\tthis.expectedCost = options.expectedCost;\n\t\tthis.statusCode = options.statusCode;\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAsCA,IAAa,yBAAb,cAA4C,eAAe;CAC1D;CACA,OAAwC;CACxC;;;;;;;;CASA,YAAY,SAAiB,SAAwC;EACpE,MAAM,SAAS,OAAO;EACtB,KAAK,eAAe,QAAQ;EAC5B,KAAK,aAAa,QAAQ;CAC3B;AACD"}
package/dist/badges.d.mts CHANGED
@@ -1,35 +1,37 @@
1
- import { f as Result, m as OpenCloudError, s as OpenCloudClientOptions, u as RequestOptions } from "./types-CvYh4SPC.mjs";
2
- import { i as RobloxLocale, r as RobloxLanguageCode } from "./data.generated-B2ceLfSn.mjs";
3
-
1
+ import { c as OpenCloudClientOptions, d as RequestOptions, g as OpenCloudError, m as Result } from "./types-CdMr_J1M.mjs";
2
+ import { i as RobloxLocale, r as RobloxLanguageCode } from "./data.generated-D_vpa5-g.mjs";
4
3
  //#region src/domains/badges/badges/types.d.ts
5
4
  /**
6
- * Awarder kind for a badge. The Roblox API only awards badges from a
7
- * `Place`, so the wire enum carries a single value; the public type
8
- * preserves the string label so future awarder kinds can be added
9
- * without a breaking change.
10
- *
11
- * @since 0.1.0
12
- */
5
+ * Awarder kind for a badge. The Roblox API only awards badges from a
6
+ * `Place`, so the wire enum carries a single value; the public type
7
+ * preserves the string label so future awarder kinds can be added
8
+ * without a breaking change.
9
+ *
10
+ * @since 0.1.0
11
+ */
13
12
  type BadgeAwarderType = "Place";
14
13
  /**
15
- * The entity that awards a badge. Always a place at present; the
16
- * `id` is the awarding place's ID and `name` its display name.
17
- *
18
- * @since 0.1.0
19
- */
14
+ * The entity that awards a badge. Always a place at present; the
15
+ * `id` is the awarding place's ID and `name` its display name.
16
+ *
17
+ * @since 0.1.0
18
+ */
20
19
  interface BadgeAwarder {
21
20
  /** Stringified ID of the awarding entity. */
22
21
  readonly id: string;
23
- /** Display name of the awarding entity. */
24
- readonly name: string;
22
+ /**
23
+ * Display name of the awarding entity, or `undefined` when the
24
+ * response omits it, as the create response does.
25
+ */
26
+ readonly name: string | undefined;
25
27
  /** Kind of awarding entity. Currently always `"Place"`. */
26
28
  readonly type: BadgeAwarderType;
27
29
  }
28
30
  /**
29
- * Award statistics for a badge.
30
- *
31
- * @since 0.1.0
32
- */
31
+ * Award statistics for a badge.
32
+ *
33
+ * @since 0.1.0
34
+ */
33
35
  interface BadgeStatistics {
34
36
  /** Total number of times the badge has been awarded. */
35
37
  readonly awardedCount: number;
@@ -39,16 +41,16 @@ interface BadgeStatistics {
39
41
  readonly winRatePercentage: number;
40
42
  }
41
43
  /**
42
- * Source of funds for the Robux fee charged on badge creation.
43
- *
44
- * @since 0.1.0
45
- */
44
+ * Source of funds for the Robux fee charged on badge creation.
45
+ *
46
+ * @since 0.1.0
47
+ */
46
48
  type BadgePaymentSource = "Group" | "User";
47
49
  /**
48
- * Parameters for creating a new badge under a universe.
49
- *
50
- * @since 0.1.0
51
- */
50
+ * Parameters for creating a new badge under a universe.
51
+ *
52
+ * @since 0.1.0
53
+ */
52
54
  interface CreateBadgeParameters {
53
55
  /** Display name of the new badge. */
54
56
  readonly name: string;
@@ -61,20 +63,20 @@ interface CreateBadgeParameters {
61
63
  /** Whether the badge should be created in the active state. */
62
64
  readonly isActive?: boolean;
63
65
  /**
64
- * Account that funds the badge creation fee. Defaults to user funds
65
- * server-side.
66
- */
66
+ * Account that funds the badge creation fee. Defaults to user funds
67
+ * server-side.
68
+ */
67
69
  readonly paymentSource?: BadgePaymentSource;
68
70
  /** Stringified ID of the universe that owns the badge. */
69
71
  readonly universeId: string;
70
72
  }
71
73
  /**
72
- * Parameters for partially updating an existing badge. Every field
73
- * except the identifier is optional; omitted fields are not included
74
- * in the JSON body so the server leaves their current values untouched.
75
- *
76
- * @since 0.1.0
77
- */
74
+ * Parameters for partially updating an existing badge. Every field
75
+ * except the identifier is optional; omitted fields are not included
76
+ * in the JSON body so the server leaves their current values untouched.
77
+ *
78
+ * @since 0.1.0
79
+ */
78
80
  interface UpdateBadgeParameters {
79
81
  /** Optional new source-language display name. */
80
82
  readonly name?: string;
@@ -86,12 +88,12 @@ interface UpdateBadgeParameters {
86
88
  readonly enabled?: boolean;
87
89
  }
88
90
  /**
89
- * A Roblox badge as exposed to SDK consumers. Fields use DX-friendly
90
- * names and types (stringified IDs, `Date` timestamps) rather than the
91
- * raw wire representation.
92
- *
93
- * @since 0.1.0
94
- */
91
+ * A Roblox badge as exposed to SDK consumers. Fields use DX-friendly
92
+ * names and types (stringified IDs, `Date` timestamps) rather than the
93
+ * raw wire representation.
94
+ *
95
+ * @since 0.1.0
96
+ */
95
97
  interface Badge {
96
98
  /** Stringified badge ID. The API returns an int64; always use this. */
97
99
  readonly id: string;
@@ -104,26 +106,26 @@ interface Badge {
104
106
  /** Source-language description shown when no localized override applies. */
105
107
  readonly description: string;
106
108
  /**
107
- * Resolved description for the requesting locale, or the source
108
- * description.
109
- */
109
+ * Resolved description for the requesting locale, or the source
110
+ * description.
111
+ */
110
112
  readonly displayDescription: string;
111
113
  /**
112
- * Resolved icon image asset ID for the requesting locale; `undefined` when
113
- * no icon is uploaded.
114
- */
114
+ * Resolved icon image asset ID for the requesting locale; `undefined` when
115
+ * no icon is uploaded.
116
+ */
115
117
  readonly displayIconImageId: string | undefined;
116
118
  /** Resolved name for the requesting locale, or the source name. */
117
119
  readonly displayName: string;
118
120
  /**
119
- * Whether the badge is currently active. Disabled badges cannot be
120
- * awarded.
121
- */
121
+ * Whether the badge is currently active. Disabled badges cannot be
122
+ * awarded.
123
+ */
122
124
  readonly enabled: boolean;
123
125
  /**
124
- * Source-language icon image asset ID; `undefined` when no icon is
125
- * uploaded.
126
- */
126
+ * Source-language icon image asset ID; `undefined` when no icon is
127
+ * uploaded.
128
+ */
127
129
  readonly iconImageId: string | undefined;
128
130
  /** Award statistics for the badge. */
129
131
  readonly statistics: BadgeStatistics;
@@ -131,37 +133,49 @@ interface Badge {
131
133
  readonly updatedAt: Date;
132
134
  }
133
135
  //#endregion
136
+ //#region src/domains/badges/free-quota/types.d.ts
137
+ /**
138
+ * Parameters for reading how many badges a universe can still create free
139
+ * of charge today.
140
+ *
141
+ * @since 0.4.0
142
+ */
143
+ interface GetFreeBadgeQuotaParameters {
144
+ /** Stringified ID of the universe whose free badge quota is read. */
145
+ readonly universeId: string;
146
+ }
147
+ //#endregion
134
148
  //#region src/domains/game-internationalization/badge-icon/types.d.ts
135
149
  /**
136
- * Parameters for uploading or replacing the per-locale icon registered
137
- * against a badge. A subsequent upload for the same `(badgeId, languageCode)`
138
- * pair replaces the existing icon for that locale. Source-language icons
139
- * are managed through `BadgesClient.uploadIcon`.
140
- *
141
- * @since 0.1.0
142
- */
150
+ * Parameters for uploading or replacing the per-locale icon registered
151
+ * against a badge. A subsequent upload for the same `(badgeId, languageCode)`
152
+ * pair replaces the existing icon for that locale. Source-language icons
153
+ * are managed through `BadgesClient.uploadIcon`.
154
+ *
155
+ * @since 0.1.0
156
+ */
143
157
  interface UploadBadgeIconLocalizationParameters {
144
158
  /** Stringified ID of the badge whose icon is being uploaded. */
145
159
  readonly badgeId: string;
146
160
  /** Image bytes to upload. PNG and JPEG are accepted by the server. */
147
161
  readonly image: Blob | Uint8Array;
148
162
  /**
149
- * Roblox wire form the icon is being uploaded for. Either the
150
- * Language form (e.g. `en`, `fil`, `zh-hans`) or the Locale form
151
- * (e.g. `en_us`, `pt_br`, `ar_001`).
152
- */
163
+ * Roblox wire form the icon is being uploaded for. Either the
164
+ * Language form (e.g. `en`, `fil`, `zh-hans`) or the Locale form
165
+ * (e.g. `en_us`, `pt_br`, `ar_001`).
166
+ */
153
167
  readonly languageCode: RobloxLanguageCode | RobloxLocale;
154
168
  }
155
169
  //#endregion
156
170
  //#region src/domains/game-internationalization/badge-name-description/types.d.ts
157
171
  /**
158
- * Parameters for updating the per-locale name and/or description registered
159
- * against a badge. Both `name` and `description` are optional; fields omitted
160
- * from the call are not included in the JSON body so the server leaves the
161
- * existing value for that locale untouched.
162
- *
163
- * @since 0.1.0
164
- */
172
+ * Parameters for updating the per-locale name and/or description registered
173
+ * against a badge. Both `name` and `description` are optional; fields omitted
174
+ * from the call are not included in the JSON body so the server leaves the
175
+ * existing value for that locale untouched.
176
+ *
177
+ * @since 0.1.0
178
+ */
165
179
  interface UpdateBadgeNameDescriptionParameters {
166
180
  /** Replacement display name for the supplied locale. */
167
181
  readonly name?: string;
@@ -170,146 +184,176 @@ interface UpdateBadgeNameDescriptionParameters {
170
184
  /** Replacement description for the supplied locale. */
171
185
  readonly description?: string;
172
186
  /**
173
- * Roblox wire form being updated. Either the Language form (e.g.
174
- * `en`, `fil`, `zh-hans`) or the Locale form (e.g. `en_us`, `pt_br`,
175
- * `ar_001`).
176
- */
187
+ * Roblox wire form being updated. Either the Language form (e.g.
188
+ * `en`, `fil`, `zh-hans`) or the Locale form (e.g. `en_us`, `pt_br`,
189
+ * `ar_001`).
190
+ */
177
191
  readonly languageCode: RobloxLanguageCode | RobloxLocale;
178
192
  }
179
193
  //#endregion
180
194
  //#region src/domains/publish/badge-icon/types.d.ts
181
195
  /**
182
- * Parameters for uploading or replacing the source-language icon
183
- * registered against a badge. A subsequent upload for the same badge
184
- * replaces the existing source icon; per-locale icon overlays live
185
- * under a separate `legacy-game-internationalization` endpoint and
186
- * are managed through `BadgesClient.localization.uploadIcon`.
187
- *
188
- * @since 0.1.0
189
- */
196
+ * Parameters for uploading or replacing the source-language icon
197
+ * registered against a badge. A subsequent upload for the same badge
198
+ * replaces the existing source icon; per-locale icon overlays live
199
+ * under a separate `legacy-game-internationalization` endpoint and
200
+ * are managed through `BadgesClient.localization.uploadIcon`.
201
+ *
202
+ * @since 0.1.0
203
+ */
190
204
  interface UploadBadgeIconParameters {
191
205
  /** Stringified ID of the badge whose icon is being uploaded. */
192
206
  readonly badgeId: string;
193
207
  /** Image bytes to upload. PNG and JPEG are accepted by the server. */
194
208
  readonly icon: Blob | Uint8Array;
195
209
  }
210
+ /**
211
+ * The source-language icon a badge icon upload stored.
212
+ *
213
+ * @since 0.4.0
214
+ */
215
+ interface UploadedBadgeIcon {
216
+ /** Stringified asset ID of the uploaded icon image. */
217
+ readonly iconImageId: string;
218
+ }
196
219
  //#endregion
197
220
  //#region src/resources/badges/client.d.ts
198
221
  interface BadgeLocalizationHandle {
199
222
  /**
200
- * Updates the per-locale display name and/or description registered against
201
- * a badge. Either `name`, `description`, or both may be supplied; omitted
202
- * fields are not forwarded so the server leaves the existing value for
203
- * that locale untouched. Mirrors the upstream `200 OK` echo body as
204
- * `undefined` data.
205
- *
206
- * @param parameters - Badge and language identifiers plus the optional
207
- * replacement values.
208
- * @param options - Optional per-request overrides.
209
- * @returns A success {@link Result} with no payload, or the
210
- * {@link OpenCloudError} that caused the request to fail.
211
- */
223
+ * Updates the per-locale display name and/or description registered against
224
+ * a badge. Either `name`, `description`, or both may be supplied; omitted
225
+ * fields are not forwarded so the server leaves the existing value for
226
+ * that locale untouched. Mirrors the upstream `200 OK` echo body as
227
+ * `undefined` data.
228
+ *
229
+ * @param parameters - Badge and language identifiers plus the optional
230
+ * replacement values.
231
+ * @param options - Optional per-request overrides.
232
+ * @returns A success {@link Result} with no payload, or the
233
+ * {@link OpenCloudError} that caused the request to fail.
234
+ */
212
235
  updateNameDescription: (parameters: UpdateBadgeNameDescriptionParameters, options?: RequestOptions) => Promise<Result<undefined, OpenCloudError>>;
213
236
  /**
214
- * Uploads or replaces the per-locale icon for a badge. A subsequent
215
- * upload for the same `(badgeId, languageCode)` pair replaces the
216
- * existing icon for that locale. Does not retry on 5xx so a duplicate
217
- * upload cannot be created if the server fails mid-write. Source-language
218
- * icons remain on {@link BadgesClient.uploadIcon}.
219
- *
220
- * No default request timeout applies to this upload; pass `options.timeout`
221
- * to set a per-call deadline.
222
- *
223
- * @param parameters - Badge and language identifiers plus the image bytes
224
- * to upload.
225
- * @param options - Optional per-request overrides.
226
- * @returns A success {@link Result} with no payload, or the
227
- * {@link OpenCloudError} that caused the request to fail.
228
- */
237
+ * Uploads or replaces the per-locale icon for a badge. A subsequent
238
+ * upload for the same `(badgeId, languageCode)` pair replaces the
239
+ * existing icon for that locale. Does not retry on 5xx so a duplicate
240
+ * upload cannot be created if the server fails mid-write. Source-language
241
+ * icons remain on {@link BadgesClient.uploadIcon}.
242
+ *
243
+ * No default request timeout applies to this upload; pass `options.timeout`
244
+ * to set a per-call deadline.
245
+ *
246
+ * @param parameters - Badge and language identifiers plus the image bytes
247
+ * to upload.
248
+ * @param options - Optional per-request overrides.
249
+ * @returns A success {@link Result} with no payload, or the
250
+ * {@link OpenCloudError} that caused the request to fail.
251
+ */
229
252
  uploadIcon: (parameters: UploadBadgeIconLocalizationParameters, options?: RequestOptions) => Promise<Result<undefined, OpenCloudError>>;
230
253
  }
231
254
  /**
232
- * Public client for the Roblox Open Cloud Badges API. Covers programmatic
233
- * badge creation under a universe, partial updates of badge configuration
234
- * (`name`, `description`, `enabled`), and source-language icon uploads.
235
- *
236
- * Wires the request builders, the injected
237
- * {@link OpenCloudClientOptions.httpClient}, and response parsers into a
238
- * single ergonomic surface. Every method returns a {@link Result} so
239
- * callers handle failure explicitly; no thrown {@link OpenCloudError}
240
- * ever escapes the client.
241
- *
242
- * @since 0.1.0
243
- *
244
- * @example
245
- *
246
- * ```ts
247
- * import { BadgesClient } from "@bedrock-rbx/ocale/badges";
248
- *
249
- * const client = new BadgesClient({ apiKey: "your-key" });
250
- * expect(client).toBeInstanceOf(BadgesClient);
251
- * ```
252
- */
253
- declare class BadgesClient {
255
+ * Public client for the Roblox Open Cloud Badges API. Covers programmatic
256
+ * badge creation under a universe, partial updates of badge configuration
257
+ * (`name`, `description`, `enabled`), and source-language icon uploads.
258
+ *
259
+ * Wires the request builders, the injected
260
+ * {@link OpenCloudClientOptions.httpClient}, and response parsers into a
261
+ * single ergonomic surface. Every method returns a {@link Result} so
262
+ * callers handle failure explicitly; no thrown {@link OpenCloudError}
263
+ * ever escapes the client.
264
+ *
265
+ * @since 0.1.0
266
+ *
267
+ * @example
268
+ *
269
+ * ```ts
270
+ * import { BadgesClient } from "@bedrock-rbx/ocale/badges";
271
+ *
272
+ * const client = new BadgesClient({ credential: { apiKey: "your-key", kind: "apiKey" } });
273
+ * expect(client).toBeInstanceOf(BadgesClient);
274
+ * ```
275
+ */
276
+ export declare class BadgesClient {
254
277
  #private;
255
278
  /**
256
- * Operation Group exposing per-locale localization Operations
257
- * (`updateNameDescription`, `uploadIcon`) backed by the
258
- * `legacy-game-internationalization` domain. Source-language values
259
- * remain on {@link BadgesClient.update} and
260
- * {@link BadgesClient.uploadIcon}; methods on this group set per-locale
261
- * overlays on top. Shares the parent client's HTTP, rate-limit, and
262
- * retry plumbing.
263
- */
279
+ * Operation Group exposing per-locale localization Operations
280
+ * (`updateNameDescription`, `uploadIcon`) backed by the
281
+ * `legacy-game-internationalization` domain. Source-language values
282
+ * remain on {@link BadgesClient.update} and
283
+ * {@link BadgesClient.uploadIcon}; methods on this group set per-locale
284
+ * overlays on top. Shares the parent client's HTTP, rate-limit, and
285
+ * retry plumbing.
286
+ */
264
287
  readonly localization: BadgeLocalizationHandle;
265
288
  /**
266
- * Creates a new {@link BadgesClient}. Configuration is frozen on
267
- * construction; per-request overrides are accepted on each method.
268
- *
269
- * @param options - Client-level configuration including the API key.
270
- */
289
+ * Creates a new {@link BadgesClient}. Configuration is frozen on
290
+ * construction; per-request overrides are accepted on each method.
291
+ *
292
+ * @param options - Client-level configuration including the API key.
293
+ */
271
294
  constructor(options: OpenCloudClientOptions);
272
295
  /**
273
- * Creates a new badge under the supplied universe.
274
- *
275
- * No default request timeout applies to this upload; pass `options.timeout`
276
- * to set a per-call deadline.
277
- *
278
- * @param parameters - Creation fields including the universe, name, and
279
- * icon image.
280
- * @param options - Optional per-request overrides.
281
- * @returns A {@link Result} wrapping the parsed {@link Badge} or the
282
- * {@link OpenCloudError} that caused the request to fail.
283
- */
296
+ * Creates a new badge under the supplied universe.
297
+ *
298
+ * No default request timeout applies to this upload; pass `options.timeout`
299
+ * to set a per-call deadline.
300
+ *
301
+ * A create whose `expectedCost` differs from the actual cost fails with a
302
+ * `BadgeCostMismatchError` and is not charged; with `expectedCost: 0`
303
+ * that means the universe's free badge quota is spent for today.
304
+ *
305
+ * @param parameters - Creation fields including the universe, name, and
306
+ * icon image.
307
+ * @param options - Optional per-request overrides.
308
+ * @returns A {@link Result} wrapping the parsed {@link Badge} or the
309
+ * {@link OpenCloudError} that caused the request to fail.
310
+ */
284
311
  create(parameters: CreateBadgeParameters, options?: RequestOptions): Promise<Result<Badge, OpenCloudError>>;
285
312
  /**
286
- * Partially updates a badge's configuration. Mirrors the upstream
287
- * `200 OK` empty response: a successful update yields `undefined`
288
- * data. Only fields explicitly provided are forwarded to the server,
289
- * so omitted fields keep their current values.
290
- *
291
- * @param parameters - Identifier plus the fields to update.
292
- * @param options - Optional per-request overrides.
293
- * @returns A success {@link Result} with no payload, or the
294
- * {@link OpenCloudError} that caused the request to fail.
295
- */
313
+ * Reads how many badges the universe can still create free of charge
314
+ * today. Each create within the quota lowers it by one. The quota resets
315
+ * daily at 00:00 UTC. Roblox answers for any universe ID, existing or not.
316
+ *
317
+ * The read is unauthenticated: it sends no credential and is served from
318
+ * `https://badges.roblox.com`, so the client `baseUrl` does not apply.
319
+ * Roblox allows 60 reads per minute per caller. A 429 waits until the
320
+ * reported `x-ratelimit-reset` before it retries.
321
+ *
322
+ * @since 0.4.0
323
+ * @param parameters - The universe to read.
324
+ * @param options - Optional per-request overrides.
325
+ * @returns A {@link Result} wrapping the free badges left today, or the
326
+ * {@link OpenCloudError} that caused the request to fail.
327
+ */
328
+ getFreeQuota(parameters: GetFreeBadgeQuotaParameters, options?: RequestOptions): Promise<Result<number, OpenCloudError>>;
329
+ /**
330
+ * Partially updates a badge's configuration. Mirrors the upstream
331
+ * `200 OK` empty response: a successful update yields `undefined`
332
+ * data. Only fields explicitly provided are forwarded to the server,
333
+ * so omitted fields keep their current values.
334
+ *
335
+ * @param parameters - Identifier plus the fields to update.
336
+ * @param options - Optional per-request overrides.
337
+ * @returns A success {@link Result} with no payload, or the
338
+ * {@link OpenCloudError} that caused the request to fail.
339
+ */
296
340
  update(parameters: UpdateBadgeParameters, options?: RequestOptions): Promise<Result<undefined, OpenCloudError>>;
297
341
  /**
298
- * Uploads or replaces the source-language icon registered against a
299
- * badge. A subsequent upload for the same badge replaces the
300
- * existing source icon. Does not retry on 5xx so a duplicate icon
301
- * upload cannot be created if the server fails mid-write.
302
- *
303
- * No default request timeout applies to this upload; pass `options.timeout`
304
- * to set a per-call deadline.
305
- *
306
- * @param parameters - Identifier plus the image bytes to upload.
307
- * @param options - Optional per-request overrides.
308
- * @returns A success {@link Result} with no payload, or the
309
- * {@link OpenCloudError} that caused the request to fail.
310
- */
311
- uploadIcon(parameters: UploadBadgeIconParameters, options?: RequestOptions): Promise<Result<undefined, OpenCloudError>>;
342
+ * Uploads or replaces the source-language icon registered against a
343
+ * badge. A subsequent upload for the same badge replaces the
344
+ * existing source icon. Does not retry on 5xx so a duplicate icon
345
+ * upload cannot be created if the server fails mid-write.
346
+ *
347
+ * No default request timeout applies to this upload; pass `options.timeout`
348
+ * to set a per-call deadline.
349
+ *
350
+ * @param parameters - Identifier plus the image bytes to upload.
351
+ * @param options - Optional per-request overrides.
352
+ * @returns A {@link Result} wrapping the uploaded icon's asset ID, or the
353
+ * {@link OpenCloudError} that caused the request to fail.
354
+ */
355
+ uploadIcon(parameters: UploadBadgeIconParameters, options?: RequestOptions): Promise<Result<UploadedBadgeIcon, OpenCloudError>>;
312
356
  }
313
357
  //#endregion
314
- export { type Badge, type BadgeAwarder, type BadgeAwarderType, type BadgePaymentSource, type BadgeStatistics, BadgesClient, type CreateBadgeParameters, type UpdateBadgeNameDescriptionParameters, type UpdateBadgeParameters, type UploadBadgeIconLocalizationParameters, type UploadBadgeIconParameters };
358
+ export type { Badge, BadgeAwarder, BadgeAwarderType, BadgePaymentSource, BadgeStatistics, CreateBadgeParameters, GetFreeBadgeQuotaParameters, UpdateBadgeNameDescriptionParameters, UpdateBadgeParameters, UploadBadgeIconLocalizationParameters, UploadBadgeIconParameters, UploadedBadgeIcon };
315
359
  //# sourceMappingURL=badges.d.mts.map
@@ -1 +1 @@
1
- {"version":3,"file":"badges.d.mts","names":[],"sources":["../src/domains/badges/badges/types.ts","../src/domains/game-internationalization/badge-icon/types.ts","../src/domains/game-internationalization/badge-name-description/types.ts","../src/domains/publish/badge-icon/types.ts","../src/resources/badges/client.ts"],"mappings":";;;;;;;;AAQA;;;;KAAY,gBAAA;AAQZ;;;;;;AAAA,UAAiB,YAAA;;WAEP,EAAA;EAIM;EAAA,SAFN,IAAA;EAUO;EAAA,SARP,IAAA,EAAM,gBAAA;AAAA;;;;;AAcN;UANO,eAAA;EAcL;EAAA,SAZF,YAAA;EAYE;EAAA,SAVF,mBAAA;EAiBV;EAAA,SAfU,iBAAA;AAAA;;;;;;KAQE,kBAAA;;;;;;UAOK,qBAAA;;WAEP,IAAA;;WAEA,WAAA;EAaA;EAAA,SAXA,YAAA;EAqBO;EAAA,SAnBP,IAAA,EAAM,IAAA,GAAO,UAAA;EAmBN;EAAA,SAjBP,QAAA;;;;;WAKA,aAAA,GAAgB,kBAAA;EA8B1B;EAAA,SA5BU,UAAA;AAAA;;;;;;;;UAUO,qBAAA;;WAEP,IAAA;;WAEA,OAAA;;WAEA,WAAA;;WAEA,OAAA;AAAA;;;;;;;AA8CW;UApCJ,KAAA;;WAEP,EAAA;ECxFV;EAAA,SD0FU,IAAA;;WAEA,OAAA,EAAS,YAAA;;WAET,SAAA,EAAW,IAAA;;WAEX,WAAA;ECtFmC;;;;EAAA,SD2FnC,kBAAA;;;;;WAKA,kBAAA;;WAEA,WAAA;;AE5GV;;;WFiHU,OAAA;;;;;WAKA,WAAA;;WAEA,UAAA,EAAY,eAAA;EE5GuB;EAAA,SF8GnC,SAAA,EAAW,IAAA;AAAA;;;;;;AA5HrB;;;;AAAY;UCEK,qCAAA;EDMA;EAAA,SCJP,OAAA;EDUM;EAAA,SCRN,KAAA,EAAO,IAAA,GAAO,UAAA;;;;;ADQR;WCFN,YAAA,EAAc,kBAAA,GAAqB,YAAA;AAAA;;;;;;ADZ7C;;;;AAAY;UEEK,oCAAA;EFMA;EAAA,SEJP,IAAA;EFUM;EAAA,SERN,OAAA;;WAEA,WAAA;;;AFMM;AAQhB;;WERU,YAAA,EAAc,kBAAA,GAAqB,YAAA;AAAA;;;;;;;AFd7C;;;;AAAY;UGCK,yBAAA;EHOA;EAAA,SGLP,OAAA;EHWM;EAAA,SGTN,IAAA,EAAM,IAAA,GAAO,UAAA;AAAA;;;UC0Eb,uBAAA;EJ/EE;AAQZ;;;;;;;;;AAMgB;AAQhB;;EIuEC,qBAAA,GACC,UAAA,EAAY,oCAAA,EACZ,OAAA,GAAU,cAAA,KACN,OAAA,CAAQ,MAAA,YAAkB,cAAA;EJ1Ef;;;;;AAMP;AAQV;;;;AAAY;AAOZ;;;;;EIsEC,UAAA,GACC,UAAA,EAAY,qCAAA,EACZ,OAAA,GAAU,cAAA,KACN,OAAA,CAAQ,MAAA,YAAkB,cAAA;AAAA;;;;;;;;;;;;;AJxDtB;AAUV;;;;;;;;;cIuEa,YAAA;EAAA;EJrDI;;;;;;;;;EAAA,SIiEA,YAAA,EAAc,uBAAA;;;;;;;EAQ9B,WAAA,CAAY,OAAA,EAAS,sBAAA;;;;;;;;;AJrCD;;;;EIsDpB,MAAA,CACC,UAAA,EAAY,qBAAA,EACZ,OAAA,GAAU,cAAA,GACR,OAAA,CAAQ,MAAA,CAAO,KAAA,EAAO,cAAA;EHnLT;;;;;;;;;;;EGkMhB,MAAA,CACC,UAAA,EAAY,qBAAA,EACZ,OAAA,GAAU,cAAA,GACR,OAAA,CAAQ,MAAA,YAAkB,cAAA;;;;;AH3Le;;;;ACV7C;;;;;;EEuNC,UAAA,CACC,UAAA,EAAY,yBAAA,EACZ,OAAA,GAAU,cAAA,GACR,OAAA,CAAQ,MAAA,YAAkB,cAAA;AAAA"}
1
+ {"version":3,"file":"badges.d.mts","names":[],"sources":["../src/domains/badges/badges/types.ts","../src/domains/badges/free-quota/types.ts","../src/domains/game-internationalization/badge-icon/types.ts","../src/domains/game-internationalization/badge-name-description/types.ts","../src/domains/publish/badge-icon/types.ts","../src/resources/badges/client.ts"],"mappings":";;;;;;;;;;;KAQY;;;;;;;UAQK;;WAEP;;;;;WAKA;;WAEA,MAAM;;;;;;;UAQC;;WAEP;;WAEA;;WAEA;;;;;;;KAQE;;;;;;UAOK;;WAEP;;WAEA;;WAEA;;WAEA,MAAM,OAAO;;WAEb;;;;;WAKA,gBAAgB;;WAEhB;;;;;;;;;UAUO;;WAEP;;WAEA;;WAEA;;WAEA;;;;;;;;;UAUO;;WAEP;;WAEA;;WAEA,SAAS;;WAET,WAAW;;WAEX;;;;;WAKA;;;;;WAKA;;WAEA;;;;;WAKA;;;;;WAKA;;WAEA,YAAY;;WAEZ,WAAW;;;;;;;;;;UCjIJ;;WAEP;;;;;;;;;;;;UCEO;;WAEP;;WAEA,OAAO,OAAO;;;;;;WAMd,cAAc,qBAAqB;;;;;;;;;;;;UCV5B;;WAEP;;WAEA;;WAEA;;;;;;WAMA,cAAc,qBAAqB;;;;;;;;;;;;;UCb5B;;WAEP;;WAEA,MAAM,OAAO;;;;;;;UAQN;;WAEP;;;;UCsFA;;;;;;;;;;;;;;EAcT,wBACC,YAAY,sCACZ,UAAU,mBACN,QAAQ,kBAAkB;;;;;;;;;;;;;;;;;EAiB/B,aACC,YAAY,uCACZ,UAAU,mBACN,QAAQ,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;qBAyBnB;;;;;;;;;;;WAYI,cAAc;;;;;;;EAQ9B,YAAY,SAAS;;;;;;;;;;;;;;;;;EAqBrB,OACC,YAAY,uBACZ,UAAU,iBACR,QAAQ,OAAO,OAAO;;;;;;;;;;;;;;;;;EAyBzB,aACC,YAAY,6BACZ,UAAU,iBACR,QAAQ,eAAe;;;;;;;;;;;;EAoB1B,OACC,YAAY,uBACZ,UAAU,iBACR,QAAQ,kBAAkB;;;;;;;;;;;;;;;EAkB7B,WACC,YAAY,2BACZ,UAAU,iBACR,QAAQ,OAAO,mBAAmB"}