@oxy.so/contracts 6.24.0 → 6.26.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.
@@ -17,6 +17,16 @@
17
17
  * is the SHAPE of what a client writes: only the keys a character has, each an
18
18
  * id-like string, a `#rrggbb` paint, a spacing in range. The client resolves
19
19
  * the ids and falls back on a default look for one it cannot draw.
20
+ *
21
+ * ## A bot's colour is its account's, not its character's
22
+ *
23
+ * A bot is painted in its account's `color` (`User.color`, a Bloom preset key):
24
+ * Bloom draws a bot account's character in it (`avatarCharacterInColor`,
25
+ * `@oxy.so/bloom` 20), so a character needs no paint of its own and a bot whose
26
+ * owner changes its colour changes everywhere at once. A character is therefore
27
+ * valid with a preset or a shape alone. `color` and `bodyColor` are still
28
+ * accepted from writers that send them, and a renderer that knows the account's
29
+ * colour ignores them.
20
30
  */
21
31
  Object.defineProperty(exports, "__esModule", { value: true });
22
32
  exports.AVATAR_PICKABLE_COLORS = exports.AVATAR_PICKABLE_SHAPES = exports.avatarCharacterSchema = exports.AVATAR_EYE_SPACING = void 0;
@@ -31,7 +41,8 @@ const idSchema = zod_1.z.string().regex(ID);
31
41
  /**
32
42
  * A character a client sends. `.strict()` so a misspelled field is a refusal
33
43
  * now rather than a look that never takes effect. A character with nothing in
34
- * it draws nothing: it needs a preset, or a shape and a paint.
44
+ * it draws nothing: it needs a preset or a shape. It needs no paint: the
45
+ * account's colour paints it (see the file comment).
35
46
  */
36
47
  exports.avatarCharacterSchema = zod_1.z
37
48
  .object({
@@ -54,8 +65,9 @@ exports.avatarCharacterSchema = zod_1.z
54
65
  .optional(),
55
66
  })
56
67
  .strict()
57
- .refine((c) => c.preset !== undefined ||
58
- (c.shape !== undefined && (c.color !== undefined || c.bodyColor !== undefined)), { message: 'A character needs a preset, or a shape and a color' });
68
+ .refine((c) => c.preset !== undefined || c.shape !== undefined, {
69
+ message: 'A character needs a preset or a shape',
70
+ });
59
71
  /** The validated character, or `null` for anything that is not one. */
60
72
  function parseAvatarCharacter(value) {
61
73
  const parsed = exports.avatarCharacterSchema.safeParse(value);
@@ -157,6 +157,25 @@ exports.moneySchema = zod_1.z
157
157
  * each read once, so the partition rule holds. A provider whose session price
158
158
  * already includes the transcription (xAI's Voice Agent) never reports it.
159
159
  *
160
+ * **`cache_write_input_tokens` is a third prompt-side sibling** (added in
161
+ * contract set 4.1.0, mirroring `@kaana.ai/contracts` 8.4.0): input tokens
162
+ * WRITTEN to a prompt cache on this request, the first-request premium a
163
+ * provider charges to create a cache entry (Anthropic's default five-minute
164
+ * write is billed at 1.25 times the input price). A token is written to the
165
+ * cache OR read from it OR neither, so it is in none of `input_tokens` and
166
+ * none of `cached_input_tokens`:
167
+ *
168
+ * ```text
169
+ * input_tokens = prompt tokens - cache reads - cache writes
170
+ * cached_input_tokens = tokens served from the cache
171
+ * cache_write_input_tokens = tokens written to the cache
172
+ * ```
173
+ *
174
+ * Only the default (five-minute) time to live is a unit; an extended-TTL write
175
+ * is not reported as this unit. A price version that does not price the unit
176
+ * refuses a settlement that reports it (`unpriced_unit`): an unpriced unit is
177
+ * never a free one.
178
+ *
160
179
  * No refinement in this package can enforce it, and saying so is part of the
161
180
  * rule: a nested report and a disjoint one are the same four non-negative
162
181
  * integers, so no predicate over a single report can tell them apart. The two
@@ -195,6 +214,7 @@ exports.USAGE_UNITS = [
195
214
  'audio_output_tokens',
196
215
  'session_milliseconds',
197
216
  'input_transcription_milliseconds',
217
+ 'cache_write_input_tokens',
198
218
  ];
199
219
  exports.usageUnitSchema = zod_1.z.enum(exports.USAGE_UNITS);
200
220
  /**
@@ -102,4 +102,4 @@ exports.INFERENCE_CONTRACT_VERSION = void 0;
102
102
  * change to, say, the catalogue reject every in-flight inference request; the
103
103
  * per-shape `schemaVersion` is what a message is validated against.
104
104
  */
105
- exports.INFERENCE_CONTRACT_VERSION = '4.0.0';
105
+ exports.INFERENCE_CONTRACT_VERSION = '4.1.0';
@@ -16,6 +16,16 @@
16
16
  * is the SHAPE of what a client writes: only the keys a character has, each an
17
17
  * id-like string, a `#rrggbb` paint, a spacing in range. The client resolves
18
18
  * the ids and falls back on a default look for one it cannot draw.
19
+ *
20
+ * ## A bot's colour is its account's, not its character's
21
+ *
22
+ * A bot is painted in its account's `color` (`User.color`, a Bloom preset key):
23
+ * Bloom draws a bot account's character in it (`avatarCharacterInColor`,
24
+ * `@oxy.so/bloom` 20), so a character needs no paint of its own and a bot whose
25
+ * owner changes its colour changes everywhere at once. A character is therefore
26
+ * valid with a preset or a shape alone. `color` and `bodyColor` are still
27
+ * accepted from writers that send them, and a renderer that knows the account's
28
+ * colour ignores them.
19
29
  */
20
30
  import { z } from 'zod';
21
31
  const ID = /^[a-z][a-z0-9_]{0,39}$/;
@@ -26,7 +36,8 @@ const idSchema = z.string().regex(ID);
26
36
  /**
27
37
  * A character a client sends. `.strict()` so a misspelled field is a refusal
28
38
  * now rather than a look that never takes effect. A character with nothing in
29
- * it draws nothing: it needs a preset, or a shape and a paint.
39
+ * it draws nothing: it needs a preset or a shape. It needs no paint: the
40
+ * account's colour paints it (see the file comment).
30
41
  */
31
42
  export const avatarCharacterSchema = z
32
43
  .object({
@@ -49,8 +60,9 @@ export const avatarCharacterSchema = z
49
60
  .optional(),
50
61
  })
51
62
  .strict()
52
- .refine((c) => c.preset !== undefined ||
53
- (c.shape !== undefined && (c.color !== undefined || c.bodyColor !== undefined)), { message: 'A character needs a preset, or a shape and a color' });
63
+ .refine((c) => c.preset !== undefined || c.shape !== undefined, {
64
+ message: 'A character needs a preset or a shape',
65
+ });
54
66
  /** The validated character, or `null` for anything that is not one. */
55
67
  export function parseAvatarCharacter(value) {
56
68
  const parsed = avatarCharacterSchema.safeParse(value);
@@ -154,6 +154,25 @@ export const moneySchema = z
154
154
  * each read once, so the partition rule holds. A provider whose session price
155
155
  * already includes the transcription (xAI's Voice Agent) never reports it.
156
156
  *
157
+ * **`cache_write_input_tokens` is a third prompt-side sibling** (added in
158
+ * contract set 4.1.0, mirroring `@kaana.ai/contracts` 8.4.0): input tokens
159
+ * WRITTEN to a prompt cache on this request, the first-request premium a
160
+ * provider charges to create a cache entry (Anthropic's default five-minute
161
+ * write is billed at 1.25 times the input price). A token is written to the
162
+ * cache OR read from it OR neither, so it is in none of `input_tokens` and
163
+ * none of `cached_input_tokens`:
164
+ *
165
+ * ```text
166
+ * input_tokens = prompt tokens - cache reads - cache writes
167
+ * cached_input_tokens = tokens served from the cache
168
+ * cache_write_input_tokens = tokens written to the cache
169
+ * ```
170
+ *
171
+ * Only the default (five-minute) time to live is a unit; an extended-TTL write
172
+ * is not reported as this unit. A price version that does not price the unit
173
+ * refuses a settlement that reports it (`unpriced_unit`): an unpriced unit is
174
+ * never a free one.
175
+ *
157
176
  * No refinement in this package can enforce it, and saying so is part of the
158
177
  * rule: a nested report and a disjoint one are the same four non-negative
159
178
  * integers, so no predicate over a single report can tell them apart. The two
@@ -192,6 +211,7 @@ export const USAGE_UNITS = [
192
211
  'audio_output_tokens',
193
212
  'session_milliseconds',
194
213
  'input_transcription_milliseconds',
214
+ 'cache_write_input_tokens',
195
215
  ];
196
216
  export const usageUnitSchema = z.enum(USAGE_UNITS);
197
217
  /**
@@ -99,4 +99,4 @@
99
99
  * change to, say, the catalogue reject every in-flight inference request; the
100
100
  * per-shape `schemaVersion` is what a message is validated against.
101
101
  */
102
- export const INFERENCE_CONTRACT_VERSION = '4.0.0';
102
+ export const INFERENCE_CONTRACT_VERSION = '4.1.0';
@@ -16,6 +16,16 @@
16
16
  * is the SHAPE of what a client writes: only the keys a character has, each an
17
17
  * id-like string, a `#rrggbb` paint, a spacing in range. The client resolves
18
18
  * the ids and falls back on a default look for one it cannot draw.
19
+ *
20
+ * ## A bot's colour is its account's, not its character's
21
+ *
22
+ * A bot is painted in its account's `color` (`User.color`, a Bloom preset key):
23
+ * Bloom draws a bot account's character in it (`avatarCharacterInColor`,
24
+ * `@oxy.so/bloom` 20), so a character needs no paint of its own and a bot whose
25
+ * owner changes its colour changes everywhere at once. A character is therefore
26
+ * valid with a preset or a shape alone. `color` and `bodyColor` are still
27
+ * accepted from writers that send them, and a renderer that knows the account's
28
+ * colour ignores them.
19
29
  */
20
30
  import { z } from 'zod';
21
31
  /** The flat shape of Bloom's `AvatarCharacter`; every field is optional (a preset supplies the rest). */
@@ -40,7 +50,8 @@ export declare const AVATAR_EYE_SPACING: {
40
50
  /**
41
51
  * A character a client sends. `.strict()` so a misspelled field is a refusal
42
52
  * now rather than a look that never takes effect. A character with nothing in
43
- * it draws nothing: it needs a preset, or a shape and a paint.
53
+ * it draws nothing: it needs a preset or a shape. It needs no paint: the
54
+ * account's colour paints it (see the file comment).
44
55
  */
45
56
  export declare const avatarCharacterSchema: z.ZodType<AvatarCharacter, unknown>;
46
57
  /** The validated character, or `null` for anything that is not one. */
@@ -742,6 +742,7 @@ export declare const modelCatalogueEntrySchema: z.ZodObject<{
742
742
  audio_output_tokens: "audio_output_tokens";
743
743
  session_milliseconds: "session_milliseconds";
744
744
  input_transcription_milliseconds: "input_transcription_milliseconds";
745
+ cache_write_input_tokens: "cache_write_input_tokens";
745
746
  }>;
746
747
  amount: z.core.$ZodBranded<z.ZodString, "ExactDecimal", "out">;
747
748
  per: z.ZodNumber;
@@ -147,6 +147,7 @@ export declare const meteredGenerationSchema: z.ZodObject<{
147
147
  audio_output_tokens: "audio_output_tokens";
148
148
  session_milliseconds: "session_milliseconds";
149
149
  input_transcription_milliseconds: "input_transcription_milliseconds";
150
+ cache_write_input_tokens: "cache_write_input_tokens";
150
151
  }>;
151
152
  quantity: z.ZodNumber;
152
153
  }, z.core.$strict>>;
@@ -140,6 +140,25 @@ export declare const moneySchema: z.ZodObject<{
140
140
  * each read once, so the partition rule holds. A provider whose session price
141
141
  * already includes the transcription (xAI's Voice Agent) never reports it.
142
142
  *
143
+ * **`cache_write_input_tokens` is a third prompt-side sibling** (added in
144
+ * contract set 4.1.0, mirroring `@kaana.ai/contracts` 8.4.0): input tokens
145
+ * WRITTEN to a prompt cache on this request, the first-request premium a
146
+ * provider charges to create a cache entry (Anthropic's default five-minute
147
+ * write is billed at 1.25 times the input price). A token is written to the
148
+ * cache OR read from it OR neither, so it is in none of `input_tokens` and
149
+ * none of `cached_input_tokens`:
150
+ *
151
+ * ```text
152
+ * input_tokens = prompt tokens - cache reads - cache writes
153
+ * cached_input_tokens = tokens served from the cache
154
+ * cache_write_input_tokens = tokens written to the cache
155
+ * ```
156
+ *
157
+ * Only the default (five-minute) time to live is a unit; an extended-TTL write
158
+ * is not reported as this unit. A price version that does not price the unit
159
+ * refuses a settlement that reports it (`unpriced_unit`): an unpriced unit is
160
+ * never a free one.
161
+ *
143
162
  * No refinement in this package can enforce it, and saying so is part of the
144
163
  * rule: a nested report and a disjoint one are the same four non-negative
145
164
  * integers, so no predicate over a single report can tell them apart. The two
@@ -161,7 +180,7 @@ export declare const moneySchema: z.ZodObject<{
161
180
  * and the "units are integers" rule holds for every modality instead of holding
162
181
  * for tokens and being quietly broken by audio.
163
182
  */
164
- export declare const USAGE_UNITS: readonly ["input_tokens", "cached_input_tokens", "output_tokens", "reasoning_tokens", "requests", "images", "audio_input_milliseconds", "audio_output_milliseconds", "video_milliseconds", "characters", "embeddings", "audio_input_tokens", "cached_audio_input_tokens", "audio_output_tokens", "session_milliseconds", "input_transcription_milliseconds"];
183
+ export declare const USAGE_UNITS: readonly ["input_tokens", "cached_input_tokens", "output_tokens", "reasoning_tokens", "requests", "images", "audio_input_milliseconds", "audio_output_milliseconds", "video_milliseconds", "characters", "embeddings", "audio_input_tokens", "cached_audio_input_tokens", "audio_output_tokens", "session_milliseconds", "input_transcription_milliseconds", "cache_write_input_tokens"];
165
184
  export declare const usageUnitSchema: z.ZodEnum<{
166
185
  input_tokens: "input_tokens";
167
186
  cached_input_tokens: "cached_input_tokens";
@@ -179,6 +198,7 @@ export declare const usageUnitSchema: z.ZodEnum<{
179
198
  audio_output_tokens: "audio_output_tokens";
180
199
  session_milliseconds: "session_milliseconds";
181
200
  input_transcription_milliseconds: "input_transcription_milliseconds";
201
+ cache_write_input_tokens: "cache_write_input_tokens";
182
202
  }>;
183
203
  /**
184
204
  * A metered quantity of ONE unit. Never money — a quantity carries no price and
@@ -202,6 +222,7 @@ export declare const usageQuantitySchema: z.ZodObject<{
202
222
  audio_output_tokens: "audio_output_tokens";
203
223
  session_milliseconds: "session_milliseconds";
204
224
  input_transcription_milliseconds: "input_transcription_milliseconds";
225
+ cache_write_input_tokens: "cache_write_input_tokens";
205
226
  }>;
206
227
  quantity: z.ZodNumber;
207
228
  }, z.core.$strict>;
@@ -245,6 +266,7 @@ export declare const unitPriceSchema: z.ZodObject<{
245
266
  audio_output_tokens: "audio_output_tokens";
246
267
  session_milliseconds: "session_milliseconds";
247
268
  input_transcription_milliseconds: "input_transcription_milliseconds";
269
+ cache_write_input_tokens: "cache_write_input_tokens";
248
270
  }>;
249
271
  amount: z.core.$ZodBranded<z.ZodString, "ExactDecimal", "out">;
250
272
  per: z.ZodNumber;
@@ -65,6 +65,7 @@ export declare const priceVersionSchema: z.ZodObject<{
65
65
  audio_output_tokens: "audio_output_tokens";
66
66
  session_milliseconds: "session_milliseconds";
67
67
  input_transcription_milliseconds: "input_transcription_milliseconds";
68
+ cache_write_input_tokens: "cache_write_input_tokens";
68
69
  }>;
69
70
  amount: z.core.$ZodBranded<z.ZodString, "ExactDecimal", "out">;
70
71
  per: z.ZodNumber;
@@ -104,6 +105,7 @@ export declare const priceSnapshotSchema: z.ZodObject<{
104
105
  audio_output_tokens: "audio_output_tokens";
105
106
  session_milliseconds: "session_milliseconds";
106
107
  input_transcription_milliseconds: "input_transcription_milliseconds";
108
+ cache_write_input_tokens: "cache_write_input_tokens";
107
109
  }>;
108
110
  amount: z.core.$ZodBranded<z.ZodString, "ExactDecimal", "out">;
109
111
  per: z.ZodNumber;
@@ -1442,6 +1442,7 @@ export declare const realtimeResponseDoneEventSchema: z.ZodObject<{
1442
1442
  audio_output_tokens: "audio_output_tokens";
1443
1443
  session_milliseconds: "session_milliseconds";
1444
1444
  input_transcription_milliseconds: "input_transcription_milliseconds";
1445
+ cache_write_input_tokens: "cache_write_input_tokens";
1445
1446
  }>;
1446
1447
  quantity: z.ZodNumber;
1447
1448
  }, z.core.$strict>>;
@@ -1570,6 +1571,7 @@ export declare const realtimeSessionClosedEventSchema: z.ZodObject<{
1570
1571
  audio_output_tokens: "audio_output_tokens";
1571
1572
  session_milliseconds: "session_milliseconds";
1572
1573
  input_transcription_milliseconds: "input_transcription_milliseconds";
1574
+ cache_write_input_tokens: "cache_write_input_tokens";
1573
1575
  }>;
1574
1576
  quantity: z.ZodNumber;
1575
1577
  }, z.core.$strict>>;
@@ -2019,6 +2021,7 @@ export declare const realtimeServerEventSchema: z.ZodDiscriminatedUnion<[z.ZodOb
2019
2021
  audio_output_tokens: "audio_output_tokens";
2020
2022
  session_milliseconds: "session_milliseconds";
2021
2023
  input_transcription_milliseconds: "input_transcription_milliseconds";
2024
+ cache_write_input_tokens: "cache_write_input_tokens";
2022
2025
  }>;
2023
2026
  quantity: z.ZodNumber;
2024
2027
  }, z.core.$strict>>;
@@ -2125,6 +2128,7 @@ export declare const realtimeServerEventSchema: z.ZodDiscriminatedUnion<[z.ZodOb
2125
2128
  audio_output_tokens: "audio_output_tokens";
2126
2129
  session_milliseconds: "session_milliseconds";
2127
2130
  input_transcription_milliseconds: "input_transcription_milliseconds";
2131
+ cache_write_input_tokens: "cache_write_input_tokens";
2128
2132
  }>;
2129
2133
  quantity: z.ZodNumber;
2130
2134
  }, z.core.$strict>>;
@@ -132,6 +132,7 @@ export declare const routingPolicySchema: z.ZodObject<{
132
132
  audio_output_tokens: "audio_output_tokens";
133
133
  session_milliseconds: "session_milliseconds";
134
134
  input_transcription_milliseconds: "input_transcription_milliseconds";
135
+ cache_write_input_tokens: "cache_write_input_tokens";
135
136
  }>;
136
137
  amount: z.core.$ZodBranded<z.ZodString, "ExactDecimal", "out">;
137
138
  per: z.ZodNumber;
@@ -164,6 +164,7 @@ export declare const inferenceStreamUsageEventSchema: z.ZodObject<{
164
164
  audio_output_tokens: "audio_output_tokens";
165
165
  session_milliseconds: "session_milliseconds";
166
166
  input_transcription_milliseconds: "input_transcription_milliseconds";
167
+ cache_write_input_tokens: "cache_write_input_tokens";
167
168
  }>;
168
169
  quantity: z.ZodNumber;
169
170
  }, z.core.$strict>>;
@@ -423,6 +424,7 @@ export declare const inferenceStreamEventSchema: z.ZodDiscriminatedUnion<[z.ZodO
423
424
  audio_output_tokens: "audio_output_tokens";
424
425
  session_milliseconds: "session_milliseconds";
425
426
  input_transcription_milliseconds: "input_transcription_milliseconds";
427
+ cache_write_input_tokens: "cache_write_input_tokens";
426
428
  }>;
427
429
  quantity: z.ZodNumber;
428
430
  }, z.core.$strict>>;
@@ -99,6 +99,7 @@ export declare const usageReservationRequestSchema: z.ZodObject<{
99
99
  audio_output_tokens: "audio_output_tokens";
100
100
  session_milliseconds: "session_milliseconds";
101
101
  input_transcription_milliseconds: "input_transcription_milliseconds";
102
+ cache_write_input_tokens: "cache_write_input_tokens";
102
103
  }>;
103
104
  quantity: z.ZodNumber;
104
105
  }, z.core.$strict>>>;
@@ -294,6 +295,7 @@ export declare const normalizedUsageReportSchema: z.ZodObject<{
294
295
  audio_output_tokens: "audio_output_tokens";
295
296
  session_milliseconds: "session_milliseconds";
296
297
  input_transcription_milliseconds: "input_transcription_milliseconds";
298
+ cache_write_input_tokens: "cache_write_input_tokens";
297
299
  }>;
298
300
  quantity: z.ZodNumber;
299
301
  }, z.core.$strict>>;
@@ -395,6 +397,7 @@ export declare const usageReceiptSchema: z.ZodObject<{
395
397
  audio_output_tokens: "audio_output_tokens";
396
398
  session_milliseconds: "session_milliseconds";
397
399
  input_transcription_milliseconds: "input_transcription_milliseconds";
400
+ cache_write_input_tokens: "cache_write_input_tokens";
398
401
  }>;
399
402
  quantity: z.ZodNumber;
400
403
  }, z.core.$strict>>;
@@ -424,6 +427,7 @@ export declare const usageReceiptSchema: z.ZodObject<{
424
427
  audio_output_tokens: "audio_output_tokens";
425
428
  session_milliseconds: "session_milliseconds";
426
429
  input_transcription_milliseconds: "input_transcription_milliseconds";
430
+ cache_write_input_tokens: "cache_write_input_tokens";
427
431
  }>;
428
432
  amount: z.core.$ZodBranded<z.ZodString, "ExactDecimal", "out">;
429
433
  per: z.ZodNumber;
@@ -99,4 +99,4 @@
99
99
  * change to, say, the catalogue reject every in-flight inference request; the
100
100
  * per-shape `schemaVersion` is what a message is validated against.
101
101
  */
102
- export declare const INFERENCE_CONTRACT_VERSION = "4.0.0";
102
+ export declare const INFERENCE_CONTRACT_VERSION = "4.1.0";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oxy.so/contracts",
3
- "version": "6.24.0",
3
+ "version": "6.26.0",
4
4
  "description": "OxyHQ API contracts — single source of truth for request/response Zod schemas and inferred types, shared by the backend and the client SDKs",
5
5
  "main": "dist/cjs/index.js",
6
6
  "module": "dist/esm/index.js",
@@ -89,6 +89,6 @@
89
89
  "@types/node": "^26.6.6",
90
90
  "jest": "^30.5.2",
91
91
  "typescript": "~6.0.3",
92
- "@oxy.so/bloom": "17.15.0"
92
+ "@oxy.so/bloom": "19.8.3"
93
93
  }
94
94
  }