@onlyworlds/sdk 4.139.0 → 4.141.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.
package/CHANGELOG.md CHANGED
@@ -5,6 +5,24 @@ earlier history lives in git log only.
5
5
 
6
6
  ## [Unreleased]
7
7
 
8
+ ## [4.141.0] - 2026-11-10
9
+
10
+ ### Added
11
+
12
+ - `OwSignInError.param`: the field the server named when it refused the code exchange, such as `ai_uses` or `ai_lifetime_minutes` on a 422 for an AI door token asked with `completeSignIn`, so that refusal can be told from any other 422 there.
13
+
14
+ ## [4.140.0] - 2026-11-10
15
+
16
+ ### Added
17
+
18
+ - `OwAiUse.rating_need`: the rating tokens a call to the use needs left today to run, the output cap or the use's worst case when it is larger. `provider` names `anthropic` or `jev`.
19
+ - `err.isAnswerNotParsed`: 422 `answer_not_parsed` (param `answer`), a use whose model answered off its promised shape twice; billed to the use's own budget, not the token rating.
20
+ - `ai()`'s notes: a refusal the provider billed (`answer_not_parsed`, or a 502 after a billed answer) is kept under the idempotency key and replayed like an answer.
21
+
22
+ ### Tests
23
+
24
+ - A layout-only bundle (`trailByPlace`, `mapSpace`) carries none of the zip library, with `readWorldFile` as the control.
25
+
8
26
  ## [4.139.0] - 2026-11-10
9
27
 
10
28
  ### Deprecated
package/dist/index.d.ts CHANGED
@@ -3137,7 +3137,9 @@ interface OwAiUse {
3137
3137
  slug: string;
3138
3138
  /** The tool that answers for its prompt and caps. */
3139
3139
  owner: string;
3140
- provider: string;
3140
+ /** Who runs the model: `anthropic` (the platform's key, or the account's own saved key once its rating is
3141
+ * spent) or `jev` (a decisions gateway; an own key never runs it). */
3142
+ provider: 'anthropic' | 'jev' | (string & {});
3141
3143
  /** The model a call on the platform's key runs. */
3142
3144
  model: string;
3143
3145
  effort: string;
@@ -3147,8 +3149,11 @@ interface OwAiUse {
3147
3149
  needs_world: boolean;
3148
3150
  /** What the body may hold, by name. */
3149
3151
  input_caps: Record<string, number>;
3150
- /** The most tokens one answer may take; a call needs at least this much rating left (or a saved own key). */
3152
+ /** The most tokens one answer may take. */
3151
3153
  output_cap: number;
3154
+ /** The rating tokens a call needs left today to run (or a saved own key, for a use it can run): the
3155
+ * output cap, or the use's worst case when it is larger. */
3156
+ rating_need: number;
3152
3157
  /** The answer is checked JSON, not text. */
3153
3158
  structured: boolean;
3154
3159
  /** A fixed price per call in rating tokens, or null: the call's actual tokens are spent. */
@@ -4245,6 +4250,13 @@ declare class OwApiError extends Error {
4245
4250
  * but `aiUses()`, its uses and its own revoke, or a hosted MCP client's token anywhere but /mcp.
4246
4251
  */
4247
4252
  get isWrongAudience(): boolean;
4253
+ /**
4254
+ * ai: the use's model answered, but not in the shape the use promises, and asked again gave no usable
4255
+ * answer either (422 `answer_not_parsed`, param `answer`). The provider billed it to the use's own budget,
4256
+ * not the token rating; under an idempotency key the same refusal is replayed. Fall back to the tool's
4257
+ * own answer, and do not retry.
4258
+ */
4259
+ get isAnswerNotParsed(): boolean;
4248
4260
  /** ask: the model gave no answer (502 `ask_failed`). Not counted; try again in a moment. */
4249
4261
  get isAskFailed(): boolean;
4250
4262
  /**
@@ -4357,11 +4369,15 @@ declare class OwSignInError extends Error {
4357
4369
  readonly status?: number;
4358
4370
  /** keel's error code, when its answer carried one. */
4359
4371
  readonly code?: string;
4372
+ /** The field the server's answer named, when it named one: `ai_uses` or `ai_lifetime_minutes` on a 422 that
4373
+ * refused the AI door token asked in the exchange (the code is spent either way). */
4374
+ readonly param?: string;
4360
4375
  /** Seconds to wait before trying again, from `Retry-After` (on a 429). */
4361
4376
  readonly retryAfter?: number;
4362
4377
  constructor(reason: OwSignInReason, message: string, opts?: {
4363
4378
  status?: number;
4364
4379
  code?: string;
4380
+ param?: string;
4365
4381
  retryAfter?: number;
4366
4382
  });
4367
4383
  }
@@ -5410,7 +5426,9 @@ declare class OwV2Client {
5410
5426
  * state, on success and on refusal; a return with another state leaves the sign-in pending;
5411
5427
  * the SDK keeps no token: the tool does. Refusals are `OwSignInError`: `state_mismatch` (no
5412
5428
  * pending sign-in, a different state, or the wrong page; nothing sent), `invalid_grant` (keel's
5413
- * 400: used, expired, or another client's code), `rate_limited`, `offline`, `failed`.
5429
+ * 400: used, expired, or another client's code), `rate_limited`, `offline`, `failed`. Each carries the server's
5430
+ * `status`, `code` and, when its answer named a field, `param`: a 422 that refused the AI door token asked
5431
+ * here names `ai_uses` or `ai_lifetime_minutes` (the code is spent either way).
5414
5432
  */
5415
5433
  completeSignIn(opts: OwSignInComplete): Promise<OwSignInResult>;
5416
5434
  /**
@@ -5488,16 +5506,19 @@ declare class OwV2Client {
5488
5506
  * a key whose first call is still running is 409 `idempotency_in_flight` (retry after `retryAfter`).
5489
5507
  * Retry with the same key and body, a few times at most, and never mint a new key to get past an
5490
5508
  * in-flight answer: when the server cannot store an answer, the key is held for a day and keeps
5491
- * answering `idempotency_in_flight` although the call ran and was billed. The client never retries
5492
- * on its own.
5509
+ * answering `idempotency_in_flight` although the call ran and was billed. A refusal the provider
5510
+ * billed (422 `answer_not_parsed`, or a 502 after a billed answer) is kept under the key and replayed
5511
+ * like an answer, so a retry never bills it twice. The client never retries on its own.
5493
5512
  *
5494
- * Refusals, none of them counted: 429 `use_ceiling` (`err.isUseCeiling`: the use's calls for the day
5513
+ * Refusals, none of them counted against the rating: 429 `use_ceiling` (`err.isUseCeiling`: the use's calls for the day
5495
5514
  * are made), 429 `use_in_flight` (`err.isUseInFlight`: another call to this use is running; wait
5496
5515
  * `retryAfter`), 429 `quota_exceeded` (`err.isQuotaExceeded`: the token rating is spent and no own key
5497
5516
  * is saved), 422 `own_key_refused` (`err.isOwnKeyRefused`), 503 `ask_unavailable`
5498
5517
  * (`err.isAskUnavailable`; with `param` `use`, this use is switched off or spent its own budget
5499
5518
  * today), 502 `ask_failed` (`err.isAskFailed`), 404 `not_found` (a use that is not listed, `param`
5500
- * `use`, or a world the account is not in), 422 for a body past the use's limits (`param` names it).
5519
+ * `use`, or a world the account is not in), 422 for a body past the use's limits (`param` names it),
5520
+ * 422 `answer_not_parsed` (`err.isAnswerNotParsed`: the answer was off its shape twice; billed to the
5521
+ * use's own budget).
5501
5522
  */
5502
5523
  ai(use: 'ask', body: OwAiAskBody, opts?: {
5503
5524
  idempotencyKey?: string;
package/dist/index.js CHANGED
@@ -363,6 +363,15 @@ var OwApiError = class extends Error {
363
363
  get isWrongAudience() {
364
364
  return this.status === 401 && this.code === "wrong_audience";
365
365
  }
366
+ /**
367
+ * ai: the use's model answered, but not in the shape the use promises, and asked again gave no usable
368
+ * answer either (422 `answer_not_parsed`, param `answer`). The provider billed it to the use's own budget,
369
+ * not the token rating; under an idempotency key the same refusal is replayed. Fall back to the tool's
370
+ * own answer, and do not retry.
371
+ */
372
+ get isAnswerNotParsed() {
373
+ return this.status === 422 && this.code === "answer_not_parsed";
374
+ }
366
375
  /** ask: the model gave no answer (502 `ask_failed`). Not counted; try again in a moment. */
367
376
  get isAskFailed() {
368
377
  return this.status === 502 && this.code === "ask_failed";
@@ -460,12 +469,13 @@ var OwNetworkError = class extends Error {
460
469
  };
461
470
  var OwSignInError = class extends Error {
462
471
  constructor(reason, message, opts = {}) {
463
- refuseUnknownOptions("OwSignInError", opts, ["status", "code", "retryAfter"]);
472
+ refuseUnknownOptions("OwSignInError", opts, ["status", "code", "param", "retryAfter"]);
464
473
  super(message);
465
474
  this.name = "OwSignInError";
466
475
  this.reason = reason;
467
476
  if (opts.status !== void 0) this.status = opts.status;
468
477
  if (opts.code !== void 0) this.code = opts.code;
478
+ if (opts.param !== void 0) this.param = opts.param;
469
479
  if (opts.retryAfter !== void 0) this.retryAfter = opts.retryAfter;
470
480
  }
471
481
  };
@@ -755,16 +765,17 @@ async function completeSignIn(baseUrl, fetchImpl, opts) {
755
765
  }
756
766
  const err = body?.error;
757
767
  const errCode = typeof err?.code === "string" ? err.code : void 0;
768
+ const errParam = typeof err?.param === "string" && err.param !== "" ? err.param : void 0;
758
769
  const errMessage = typeof err?.message === "string" ? err.message : void 0;
759
770
  if (res.status === 429) {
760
- throw new OwSignInError("rate_limited", errMessage ?? "Too many sign-in attempts. Wait a while, then try again.", { status: 429, code: errCode, retryAfter });
771
+ throw new OwSignInError("rate_limited", errMessage ?? "Too many sign-in attempts. Wait a while, then try again.", { status: 429, code: errCode, param: errParam, retryAfter });
761
772
  }
762
773
  if (res.status === 400 && errCode === "invalid_grant") {
763
- throw new OwSignInError("invalid_grant", errMessage ?? "The sign-in code could not be exchanged: it was used, expired, or made for another tool. Start again.", { status: 400, code: errCode });
774
+ throw new OwSignInError("invalid_grant", errMessage ?? "The sign-in code could not be exchanged: it was used, expired, or made for another tool. Start again.", { status: 400, code: errCode, param: errParam });
764
775
  }
765
776
  const ok = body;
766
777
  if (!res.ok || typeof ok?.token !== "string" || ok.token === "" || typeof ok.account?.id !== "string") {
767
- throw new OwSignInError("failed", errMessage ?? `Signing in did not work (${res.status}).`, { status: res.status, code: errCode });
778
+ throw new OwSignInError("failed", errMessage ?? `Signing in did not work (${res.status}).`, { status: res.status, code: errCode, param: errParam });
768
779
  }
769
780
  return {
770
781
  token: ok.token,
@@ -2175,7 +2186,9 @@ var OwV2Client = class {
2175
2186
  * state, on success and on refusal; a return with another state leaves the sign-in pending;
2176
2187
  * the SDK keeps no token: the tool does. Refusals are `OwSignInError`: `state_mismatch` (no
2177
2188
  * pending sign-in, a different state, or the wrong page; nothing sent), `invalid_grant` (keel's
2178
- * 400: used, expired, or another client's code), `rate_limited`, `offline`, `failed`.
2189
+ * 400: used, expired, or another client's code), `rate_limited`, `offline`, `failed`. Each carries the server's
2190
+ * `status`, `code` and, when its answer named a field, `param`: a 422 that refused the AI door token asked
2191
+ * here names `ai_uses` or `ai_lifetime_minutes` (the code is spent either way).
2179
2192
  */
2180
2193
  async completeSignIn(opts) {
2181
2194
  only("completeSignIn", opts, ["clientId", "storage", "url", "aiUses", "aiLifetimeMinutes"]);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@onlyworlds/sdk",
3
- "version": "4.139.0",
3
+ "version": "4.141.0",
4
4
  "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
5
5
  "type": "module",
6
6
  "exports": {