@dork-labs/cloud-api 0.75.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 (104) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +192 -0
  3. package/dist/billing.d.ts +328 -0
  4. package/dist/billing.d.ts.map +1 -0
  5. package/dist/billing.js +267 -0
  6. package/dist/billing.js.map +1 -0
  7. package/dist/client.d.ts +130 -0
  8. package/dist/client.d.ts.map +1 -0
  9. package/dist/client.js +192 -0
  10. package/dist/client.js.map +1 -0
  11. package/dist/connections.d.ts +281 -0
  12. package/dist/connections.d.ts.map +1 -0
  13. package/dist/connections.js +241 -0
  14. package/dist/connections.js.map +1 -0
  15. package/dist/index.d.ts +31 -0
  16. package/dist/index.d.ts.map +1 -0
  17. package/dist/index.js +31 -0
  18. package/dist/index.js.map +1 -0
  19. package/dist/inference.d.ts +123 -0
  20. package/dist/inference.d.ts.map +1 -0
  21. package/dist/inference.js +114 -0
  22. package/dist/inference.js.map +1 -0
  23. package/dist/instances.d.ts +60 -0
  24. package/dist/instances.d.ts.map +1 -0
  25. package/dist/instances.js +65 -0
  26. package/dist/instances.js.map +1 -0
  27. package/dist/primitives.d.ts +74 -0
  28. package/dist/primitives.d.ts.map +1 -0
  29. package/dist/primitives.js +98 -0
  30. package/dist/primitives.js.map +1 -0
  31. package/dist/problem.d.ts +96 -0
  32. package/dist/problem.d.ts.map +1 -0
  33. package/dist/problem.js +94 -0
  34. package/dist/problem.js.map +1 -0
  35. package/dist/remote.d.ts +268 -0
  36. package/dist/remote.d.ts.map +1 -0
  37. package/dist/remote.js +267 -0
  38. package/dist/remote.js.map +1 -0
  39. package/dist/routes.d.ts +273 -0
  40. package/dist/routes.d.ts.map +1 -0
  41. package/dist/routes.js +302 -0
  42. package/dist/routes.js.map +1 -0
  43. package/dist/seats.d.ts +529 -0
  44. package/dist/seats.d.ts.map +1 -0
  45. package/dist/seats.js +266 -0
  46. package/dist/seats.js.map +1 -0
  47. package/dist/session.d.ts +135 -0
  48. package/dist/session.d.ts.map +1 -0
  49. package/dist/session.js +143 -0
  50. package/dist/session.js.map +1 -0
  51. package/fixtures/v1/billing/balance-owed.json +16 -0
  52. package/fixtures/v1/billing/balance.json +16 -0
  53. package/fixtures/v1/billing/entitlements-free.json +34 -0
  54. package/fixtures/v1/billing/hosted-page.json +3 -0
  55. package/fixtures/v1/billing/nudge.json +9 -0
  56. package/fixtures/v1/billing/price-list.json +13 -0
  57. package/fixtures/v1/billing/statement.json +5 -0
  58. package/fixtures/v1/billing/usage-by-model.json +21 -0
  59. package/fixtures/v1/connections/catalog.json +12 -0
  60. package/fixtures/v1/connections/events-ack.json +3 -0
  61. package/fixtures/v1/connections/events-pull.json +16 -0
  62. package/fixtures/v1/connections/execution.json +12 -0
  63. package/fixtures/v1/connections/list.json +16 -0
  64. package/fixtures/v1/connections/usage.json +16 -0
  65. package/fixtures/v1/index.json +58 -0
  66. package/fixtures/v1/inference/models.json +17 -0
  67. package/fixtures/v1/inference/token-revoke.json +3 -0
  68. package/fixtures/v1/inference/token.json +14 -0
  69. package/fixtures/v1/instances/heartbeat.json +5 -0
  70. package/fixtures/v1/instances/list.json +15 -0
  71. package/fixtures/v1/instances/revoke.json +3 -0
  72. package/fixtures/v1/problem/handle-tombstoned.json +6 -0
  73. package/fixtures/v1/problem/person-seat-required.json +7 -0
  74. package/fixtures/v1/problem/unauthenticated.json +7 -0
  75. package/fixtures/v1/remote/address.json +5 -0
  76. package/fixtures/v1/remote/command-keepalive.json +4 -0
  77. package/fixtures/v1/remote/command-open.json +6 -0
  78. package/fixtures/v1/remote/commands-ack.json +3 -0
  79. package/fixtures/v1/remote/credential.json +7 -0
  80. package/fixtures/v1/remote/custom-address.json +12 -0
  81. package/fixtures/v1/remote/designation.json +5 -0
  82. package/fixtures/v1/remote/enrolment.json +5 -0
  83. package/fixtures/v1/remote/events.json +3 -0
  84. package/fixtures/v1/remote/open.json +5 -0
  85. package/fixtures/v1/remote/status-closed.json +7 -0
  86. package/fixtures/v1/remote/status-open.json +10 -0
  87. package/fixtures/v1/remote/wake-token.json +5 -0
  88. package/fixtures/v1/seats/addons.json +11 -0
  89. package/fixtures/v1/seats/agent.json +9 -0
  90. package/fixtures/v1/seats/grants.json +20 -0
  91. package/fixtures/v1/seats/inbox-browse.json +17 -0
  92. package/fixtures/v1/seats/inbox-pull.json +17 -0
  93. package/fixtures/v1/seats/invitation.json +9 -0
  94. package/fixtures/v1/seats/members.json +12 -0
  95. package/fixtures/v1/seats/org.json +7 -0
  96. package/fixtures/v1/seats/presence.json +6 -0
  97. package/fixtures/v1/seats/seat.json +21 -0
  98. package/fixtures/v1/session/account-export.json +6 -0
  99. package/fixtures/v1/session/device-code.json +8 -0
  100. package/fixtures/v1/session/device-token-pending.json +4 -0
  101. package/fixtures/v1/session/device-token.json +7 -0
  102. package/fixtures/v1/session/signed-in.json +14 -0
  103. package/fixtures/v1/session/signed-out.json +4 -0
  104. package/package.json +58 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Dorian Collier
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,192 @@
1
+ # @dork-labs/cloud-api
2
+
3
+ The public wire contract for DorkOS Cloud: Zod schemas for the `/v1` surface, the types they
4
+ infer, the route table, and a thin `fetch` client.
5
+
6
+ This package is the agreement between the DorkOS app and the hosted service. Both sides build
7
+ against it, and neither side gets to change the wire without changing it here first.
8
+
9
+ ```bash
10
+ npm install @dork-labs/cloud-api zod
11
+ ```
12
+
13
+ ## Two entry points
14
+
15
+ ```ts
16
+ // Schemas, types and route paths. No network code, so you can validate
17
+ // a payload without pulling in a client.
18
+ import { EntitlementsSchema, ProblemSchema, V1_ROUTES, v1Path } from '@dork-labs/cloud-api';
19
+
20
+ // The thin fetch client. No Node-only import, so a CLI, a server and a
21
+ // browser can all use it.
22
+ import { createCloudApiClient } from '@dork-labs/cloud-api/client';
23
+
24
+ const cloud = createCloudApiClient({
25
+ baseUrl: process.env.MY_CLOUD_ORIGIN!, // no origin is baked into this package
26
+ token: () => myTokenStore.read(),
27
+ });
28
+
29
+ const entitlements = await cloud.get(V1_ROUTES.entitlements, EntitlementsSchema);
30
+ const seat = await cloud.get(v1Path.seat(seatId), SeatSchema);
31
+ ```
32
+
33
+ Every response is either the route's success schema or the `Problem` envelope. The client throws
34
+ `CloudApiProblemError` for a refusal the service described, and `CloudApiResponseError` when the
35
+ body is neither.
36
+
37
+ ## What is in the contract
38
+
39
+ | Group | Covers |
40
+ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
41
+ | Session and account | `GET /v1/session`, `GET /v1/account`, `POST /v1/account/export` |
42
+ | Device link | `POST /v1/device/code`, `POST /v1/device/token` (RFC 8628) |
43
+ | Instances | heartbeat, revoke, list, organization re-link |
44
+ | Managed connections | catalog, toolkits, connections, authentication flows, authority commands, executions, the lease-based event pull and acknowledgement, usage |
45
+ | Billing | `GET /v1/entitlements`, `/v1/balance`, `/v1/usage`, `/v1/price-list`, `/v1/nudge`, `POST /v1/checkout`, `/v1/topup`, `/v1/portal`, `GET /v1/statement` |
46
+ | Inference | `POST /v1/inference/tokens`, `GET /v1/inference/models`, token revocation |
47
+ | Seats, orgs and addresses | organizations, membership, invitations, agents and claims, seats, addresses, grants, add-ons, the seat inbox, presence |
48
+ | Remote access | status, open/close, wake tokens, enrolment, canonical and custom addresses, designation, instance credentials, the command stream and its acknowledgement, event batches |
49
+ | Shared | the `Problem` envelope, bearer auth, cursor pagination, the `X-DorkOS-Wire: 1` header |
50
+
51
+ ### What is deliberately not in it
52
+
53
+ The browser-facing `/api/auth/*` endpoints, the account and admin pages, and
54
+ `POST /api/instances/pending` are a user interface of one application rather than a
55
+ machine-to-machine wire. Publishing them would freeze a dependency's internals into a machine
56
+ contract. The two device-code endpoints are the one exception: they live under `/api/auth/` today
57
+ but are a machine wire, so they are here.
58
+
59
+ The closed-address browser surface — the page an address serves while the machine is asleep,
60
+ and the authorized reopen path on it — is excluded on the same grounds. The omission is a
61
+ decision, not a gap.
62
+
63
+ ## The rules this package holds itself to
64
+
65
+ ### Additive within a major
66
+
67
+ Within `/v1`, the only changes allowed are **new endpoints and new optional fields**. The service
68
+ accepts the previous minor of this package, so a client one release behind keeps working.
69
+
70
+ Removing a field, or making an optional field required, is a `/v2` change, served beside `/v1`
71
+ for at least two releases. A change to a field's meaning is the same thing wearing a disguise:
72
+ if code that was correct before is wrong after, it is not additive.
73
+
74
+ ### Catalog blindness
75
+
76
+ **No type here enumerates the subscription catalog or the model catalog.** `planId`, `skuId`,
77
+ `modelId`, add-on kinds, `catalogVersion` and every other catalog-shaped identifier are opaque
78
+ strings. Not a `z.enum`, and equally not a union of literals, a `z.nativeEnum`, a hand-written
79
+ string-literal union, a `const` array a schema is derived from, or a value named in a
80
+ `.describe()`, a `.default()` or an `@example`.
81
+
82
+ A _value_ a caller happens to be on is fine. The _set_ is not: this package publishes to public
83
+ npm, and a `.d.ts` that enumerates the ladder publishes it permanently.
84
+
85
+ The practical consequence for consumers: subscription-specific interface behaviour is driven by
86
+ the **limit values** and the **server-supplied display string**, never by a switch on `planId`.
87
+ There is no compile-time exhaustiveness over subscriptions here, deliberately.
88
+
89
+ Enums that are fine, because they describe mechanism rather than catalog: the `Problem` codes,
90
+ the remote `mode` and `state`, `remoteAccess`, `customAddress`, `support`, `costBasis`, the
91
+ `supports` booleans, `groupBy`, the refusal reasons, and the RFC 8628 error set. Each one is
92
+ listed by name with its reason in `src/__tests__/catalog-blindness.test.ts`, and a new exported
93
+ enum fails that test until somebody writes down why it is mechanism.
94
+
95
+ ### Money is never a number
96
+
97
+ Every amount is an **integer count of micro-units carried as a string** (`MicroAmountSchema`). A
98
+ `z.number()` on an amount is a precision bug, not a style choice.
99
+
100
+ ### No origin baked in
101
+
102
+ No host, origin or URL literal appears in this package. Inference endpoints are runtime values
103
+ the mint call returns, and the client takes its `baseUrl` from the caller.
104
+
105
+ No supplier is named anywhere. The two exceptions are the field names
106
+ `endpoints.anthropicMessages` and `endpoints.openaiChat`, and they are a deliberate carve-out
107
+ rather than an oversight: they name a **request format** a caller encodes in — both are de-facto
108
+ public standards — not a supplier a request is routed to. Which provider actually serves a
109
+ request is not part of this contract and is published nowhere.
110
+
111
+ ### Where amounts appear, and where they do not
112
+
113
+ Three routes carry amounts, and it is worth being precise about which, because "no prices here"
114
+ would be a comfortable claim and a false one:
115
+
116
+ - **`GET /v1/price-list`** publishes the per-model list. That is its whole job.
117
+ - **`GET /v1/usage`** returns, per row and in the totals, both `listPriceMicro` (the upstream
118
+ list price) and `dorkosPriceMicro` (what DorkOS charged). Publishing both means publishing the
119
+ difference, and that is the point rather than an accident: somebody paying for inference
120
+ through us can see exactly what the routing costs them without asking. If that ever stops
121
+ being the intent, the field to drop is `listPriceMicro`, and dropping it is a `/v2` change.
122
+ - **`GET /v1/nudge`** returns one already-computed comparison — one subscription, one price, one
123
+ subtraction the server already did. The client renders it and computes nothing.
124
+
125
+ Nothing else carries an amount. In particular, no inference route does: not a rate, not a
126
+ multiplier, not a unit cost. And no route anywhere carries a supplier's terms.
127
+
128
+ Fields typed `SecretValueSchema` are returned **once**: hold them as credential references, never
129
+ as configuration strings, and never log them.
130
+
131
+ ## Conformance fixtures
132
+
133
+ `fixtures/v1/**.json` is a shared corpus of example payloads, with `fixtures/v1/index.json`
134
+ naming the exported schema that validates each one. Both sides of the wire can implement against
135
+ the same examples; `src/__tests__/fixtures.test.ts` proves every example is valid and that the
136
+ manifest and the directory have not drifted apart.
137
+
138
+ Every example is synthetic: opaque identifiers, RFC 2606 `.invalid` hosts, and no real catalog
139
+ value anywhere.
140
+
141
+ ```ts
142
+ import entitlements from '@dork-labs/cloud-api/fixtures/v1/billing/entitlements-free.json' with { type: 'json' };
143
+ ```
144
+
145
+ ## Versioning, and the range to depend on
146
+
147
+ This package's version **equals the DorkOS app version**, published atomically with it or not at
148
+ all.
149
+
150
+ That has a consequence worth stating plainly, because it bites silently. Lockstep bumps this
151
+ package's **minor** on every app release, and on a `0.x` version npm reads `^0.75.0` as
152
+ `>=0.75.0 <0.76.0`. **A caret range would lock you out of every future release.** While this
153
+ package is pre-1.0, depend on it as:
154
+
155
+ ```json
156
+ { "dependencies": { "@dork-labs/cloud-api": ">=0.75.0 <1" } }
157
+ ```
158
+
159
+ or as an exact pin your own release process bumps.
160
+
161
+ ## Dependencies
162
+
163
+ `zod` is a **peer dependency** (`^4.6.2`), so a consumer that already has it gets one copy rather
164
+ than two — two copies mean two answers to `instanceof`, and schemas that silently stop
165
+ recognising each other. The range names the lowest version actually built and tested against,
166
+ not the whole major: this package uses `z.iso.datetime` and Zod 4's `.def` internals, and a range
167
+ wider than what CI resolves would be a compatibility claim nothing checks.
168
+
169
+ There are **zero workspace dependencies**. Nothing here imports another package in this
170
+ monorepo, and nothing in `dependencies`, `peerDependencies` or `optionalDependencies` resolves to
171
+ one, so the package installs from public npm into a checkout that has none of this repository in
172
+ it. `src/__tests__/packaging.test.ts` proves it from the manifest, from the imports, and from the
173
+ workspace lockfile. The shared ESLint and TypeScript configs are `devDependencies`, which npm
174
+ strips from the published tarball.
175
+
176
+ ## Development
177
+
178
+ ```bash
179
+ pnpm --filter @dork-labs/cloud-api build # ESM + .d.ts into dist/
180
+ pnpm --filter @dork-labs/cloud-api typecheck
181
+ pnpm --filter @dork-labs/cloud-api lint
182
+ pnpm vitest run packages/cloud-api # from the repo root
183
+ ```
184
+
185
+ The catalog-blindness suite has one case that needs the real catalog values, which cannot live in
186
+ this repository. Supply them to run it:
187
+
188
+ ```bash
189
+ DORKOS_CATALOG_BLINDNESS_VALUES="value-a,value-b" pnpm vitest run packages/cloud-api
190
+ ```
191
+
192
+ Unset, that case is reported as skipped rather than passing quietly. Set but empty, it fails.
@@ -0,0 +1,328 @@
1
+ import { z } from 'zod';
2
+ /**
3
+ * How remote access works for the caller.
4
+ *
5
+ * Mechanism, not catalog: it says how the tunnel behaves, not what anybody
6
+ * bought.
7
+ */
8
+ export declare const RemoteAccessCapabilitySchema: z.ZodEnum<{
9
+ byo: "byo";
10
+ on_demand: "on_demand";
11
+ always_available: "always_available";
12
+ }>;
13
+ /** Whether a custom address is unavailable, purchasable as an add-on, or already included. */
14
+ export declare const CustomAddressCapabilitySchema: z.ZodEnum<{
15
+ none: "none";
16
+ addon: "addon";
17
+ included: "included";
18
+ }>;
19
+ /** Which support channel the caller reaches. */
20
+ export declare const SupportCapabilitySchema: z.ZodEnum<{
21
+ community: "community";
22
+ priority: "priority";
23
+ }>;
24
+ /**
25
+ * The seat block of the entitlement.
26
+ *
27
+ * There is deliberately no field here for a count of local agents. Local agents
28
+ * are free and unlimited and no cloud surface counts them — the absence is part
29
+ * of the contract, and `src/__tests__/catalog-blindness.test.ts` keeps it.
30
+ */
31
+ export declare const EntitlementSeatsSchema: z.ZodObject<{
32
+ total: z.ZodNumber;
33
+ assigned: z.ZodNumber;
34
+ byKind: z.ZodObject<{
35
+ person: z.ZodNumber;
36
+ agent: z.ZodNumber;
37
+ }, z.core.$strip>;
38
+ }, z.core.$strip>;
39
+ /** The measurable limits of the caller`s entitlement. */
40
+ export declare const EntitlementLimitsSchema: z.ZodObject<{
41
+ personSeatsIncluded: z.ZodNumber;
42
+ agentSeatsIncluded: z.ZodNumber;
43
+ includedCreditsMicro: z.ZodString;
44
+ cloudHours: z.ZodNumber;
45
+ storageGb: z.ZodNumber;
46
+ remoteAccess: z.ZodEnum<{
47
+ byo: "byo";
48
+ on_demand: "on_demand";
49
+ always_available: "always_available";
50
+ }>;
51
+ alwaysAvailableInstances: z.ZodNumber;
52
+ customAddress: z.ZodEnum<{
53
+ none: "none";
54
+ addon: "addon";
55
+ included: "included";
56
+ }>;
57
+ managedConnectionActions: z.ZodNullable<z.ZodNumber>;
58
+ support: z.ZodEnum<{
59
+ community: "community";
60
+ priority: "priority";
61
+ }>;
62
+ emailAddressPerSeat: z.ZodBoolean;
63
+ }, z.core.$strip>;
64
+ /**
65
+ * `GET /v1/entitlements` — what the caller is allowed to do.
66
+ *
67
+ * A caller with no subscription gets 200 and the free entitlement, never a 404.
68
+ * Somebody who has never touched billing is a valid caller and the normal case.
69
+ *
70
+ * `planId` is opaque. There is no compile-time exhaustiveness over plans here,
71
+ * deliberately: a client renders `planDisplayName` and branches on the limit
72
+ * values, never on the identifier.
73
+ */
74
+ export declare const EntitlementsSchema: z.ZodObject<{
75
+ planId: z.ZodString;
76
+ planDisplayName: z.ZodString;
77
+ periodStart: z.ZodISODateTime;
78
+ periodEnd: z.ZodISODateTime;
79
+ limits: z.ZodObject<{
80
+ personSeatsIncluded: z.ZodNumber;
81
+ agentSeatsIncluded: z.ZodNumber;
82
+ includedCreditsMicro: z.ZodString;
83
+ cloudHours: z.ZodNumber;
84
+ storageGb: z.ZodNumber;
85
+ remoteAccess: z.ZodEnum<{
86
+ byo: "byo";
87
+ on_demand: "on_demand";
88
+ always_available: "always_available";
89
+ }>;
90
+ alwaysAvailableInstances: z.ZodNumber;
91
+ customAddress: z.ZodEnum<{
92
+ none: "none";
93
+ addon: "addon";
94
+ included: "included";
95
+ }>;
96
+ managedConnectionActions: z.ZodNullable<z.ZodNumber>;
97
+ support: z.ZodEnum<{
98
+ community: "community";
99
+ priority: "priority";
100
+ }>;
101
+ emailAddressPerSeat: z.ZodBoolean;
102
+ }, z.core.$strip>;
103
+ used: z.ZodObject<{
104
+ personSeats: z.ZodNumber;
105
+ agentSeats: z.ZodNumber;
106
+ }, z.core.$strip>;
107
+ seats: z.ZodObject<{
108
+ total: z.ZodNumber;
109
+ assigned: z.ZodNumber;
110
+ byKind: z.ZodObject<{
111
+ person: z.ZodNumber;
112
+ agent: z.ZodNumber;
113
+ }, z.core.$strip>;
114
+ }, z.core.$strip>;
115
+ canCreateSeat: z.ZodBoolean;
116
+ canInviteMember: z.ZodBoolean;
117
+ staleAt: z.ZodISODateTime;
118
+ }, z.core.$strip>;
119
+ /** What the caller is allowed to do. */
120
+ export type Entitlements = z.infer<typeof EntitlementsSchema>;
121
+ /**
122
+ * `GET /v1/balance` — the caller`s credit position.
123
+ *
124
+ * `owedMicro` is not optional and not cosmetic: it is debt carried from a turn
125
+ * that overran its reservation. When it is non-zero an interface must show it,
126
+ * and a purchase that repays it renders the repayment as its own line before
127
+ * the new balance rather than as a quietly smaller number.
128
+ */
129
+ export declare const BalanceSchema: z.ZodObject<{
130
+ allowance: z.ZodObject<{
131
+ grantedMicro: z.ZodString;
132
+ remainingMicro: z.ZodString;
133
+ resetsAt: z.ZodISODateTime;
134
+ }, z.core.$strip>;
135
+ purchased: z.ZodObject<{
136
+ remainingMicro: z.ZodString;
137
+ }, z.core.$strip>;
138
+ heldMicro: z.ZodString;
139
+ owedMicro: z.ZodString;
140
+ autoReload: z.ZodObject<{
141
+ enabled: z.ZodBoolean;
142
+ ceilingMicro: z.ZodNullable<z.ZodString>;
143
+ }, z.core.$strip>;
144
+ }, z.core.$strip>;
145
+ /** The caller`s credit position. */
146
+ export type Balance = z.infer<typeof BalanceSchema>;
147
+ /**
148
+ * Where a usage line`s price came from.
149
+ *
150
+ * `published_price` is the published DorkOS price. It is a separate value from
151
+ * `managed`, which means rates an organization configured for itself and
152
+ * explicitly not a public price — rendering published prices under `managed`
153
+ * would tell a person their rate is non-public, which inverts the meaning.
154
+ */
155
+ export declare const CostBasisSchema: z.ZodEnum<{
156
+ byo_key: "byo_key";
157
+ managed: "managed";
158
+ published_price: "published_price";
159
+ }>;
160
+ /** Where a usage line`s price came from. */
161
+ export type CostBasis = z.infer<typeof CostBasisSchema>;
162
+ /**
163
+ * How a credit or subscription position reads at a glance.
164
+ *
165
+ * Widened past subscription language on purpose: `exhausted` describes a credit
166
+ * balance that has run out, which a subscription vocabulary has no word for.
167
+ */
168
+ export declare const UsageStateSchema: z.ZodEnum<{
169
+ inactive: "inactive";
170
+ active: "active";
171
+ grace: "grace";
172
+ exhausted: "exhausted";
173
+ unknown: "unknown";
174
+ }>;
175
+ /** How to group a usage query. */
176
+ export declare const UsageGroupBySchema: z.ZodEnum<{
177
+ seat: "seat";
178
+ model: "model";
179
+ day: "day";
180
+ }>;
181
+ /** `GET /v1/usage` query parameters. */
182
+ export declare const UsageQuerySchema: z.ZodObject<{
183
+ from: z.ZodISODateTime;
184
+ to: z.ZodISODateTime;
185
+ groupBy: z.ZodEnum<{
186
+ seat: "seat";
187
+ model: "model";
188
+ day: "day";
189
+ }>;
190
+ }, z.core.$strip>;
191
+ /**
192
+ * One row of the caller`s usage.
193
+ *
194
+ * Carries BOTH the upstream list price and what DorkOS charged, which means it
195
+ * carries the difference between them. That is deliberate rather than
196
+ * accidental: somebody paying for inference through DorkOS can see what the
197
+ * routing costs them without having to ask. Dropping `listPriceMicro` is the
198
+ * change that would undo it, and dropping a field is a `/v2` change.
199
+ *
200
+ * There is deliberately no supplier field and no price-list version identifier
201
+ * here. Neither is published, and neither may be inferred client-side.
202
+ */
203
+ export declare const UsageRowSchema: z.ZodObject<{
204
+ key: z.ZodString;
205
+ displayName: z.ZodString;
206
+ units: z.ZodNumber;
207
+ unit: z.ZodString;
208
+ listPriceMicro: z.ZodString;
209
+ dorkosPriceMicro: z.ZodString;
210
+ costBasis: z.ZodEnum<{
211
+ byo_key: "byo_key";
212
+ managed: "managed";
213
+ published_price: "published_price";
214
+ }>;
215
+ }, z.core.$strip>;
216
+ /** `GET /v1/usage` — the caller`s own usage for a window. */
217
+ export declare const UsageResponseSchema: z.ZodObject<{
218
+ from: z.ZodISODateTime;
219
+ to: z.ZodISODateTime;
220
+ groupBy: z.ZodEnum<{
221
+ seat: "seat";
222
+ model: "model";
223
+ day: "day";
224
+ }>;
225
+ state: z.ZodEnum<{
226
+ inactive: "inactive";
227
+ active: "active";
228
+ grace: "grace";
229
+ exhausted: "exhausted";
230
+ unknown: "unknown";
231
+ }>;
232
+ rows: z.ZodArray<z.ZodObject<{
233
+ key: z.ZodString;
234
+ displayName: z.ZodString;
235
+ units: z.ZodNumber;
236
+ unit: z.ZodString;
237
+ listPriceMicro: z.ZodString;
238
+ dorkosPriceMicro: z.ZodString;
239
+ costBasis: z.ZodEnum<{
240
+ byo_key: "byo_key";
241
+ managed: "managed";
242
+ published_price: "published_price";
243
+ }>;
244
+ }, z.core.$strip>>;
245
+ totals: z.ZodObject<{
246
+ listPriceMicro: z.ZodString;
247
+ dorkosPriceMicro: z.ZodString;
248
+ }, z.core.$strip>;
249
+ }, z.core.$strip>;
250
+ /** The caller`s own usage for a window. */
251
+ export type UsageResponse = z.infer<typeof UsageResponseSchema>;
252
+ /** One entry of the published price list. */
253
+ export declare const PriceListEntrySchema: z.ZodObject<{
254
+ modelId: z.ZodString;
255
+ displayName: z.ZodString;
256
+ unit: z.ZodString;
257
+ inputMicro: z.ZodString;
258
+ outputMicro: z.ZodString;
259
+ }, z.core.$strip>;
260
+ /**
261
+ * `GET /v1/price-list` — the published per-model price list.
262
+ *
263
+ * Published by design. It carries nothing about how the list is arrived at and
264
+ * no commercial terms. It is not the only route carrying an amount — `/v1/usage`
265
+ * and `/v1/nudge` both do, for the caller's own figures — but it is the only one
266
+ * that publishes the list itself.
267
+ */
268
+ export declare const PriceListResponseSchema: z.ZodObject<{
269
+ version: z.ZodString;
270
+ effectiveFrom: z.ZodISODateTime;
271
+ entries: z.ZodArray<z.ZodObject<{
272
+ modelId: z.ZodString;
273
+ displayName: z.ZodString;
274
+ unit: z.ZodString;
275
+ inputMicro: z.ZodString;
276
+ outputMicro: z.ZodString;
277
+ }, z.core.$strip>>;
278
+ }, z.core.$strip>;
279
+ /**
280
+ * `GET /v1/nudge` — one already-computed comparison, delivered reduced.
281
+ *
282
+ * The server does the subtraction; the client renders what it is given and
283
+ * computes nothing. Exactly one subscription and one price ever appear. The
284
+ * route sits behind a server flag and answers 404 until it is switched on, so a
285
+ * client treats 404 here as "no nudge", not as an error.
286
+ */
287
+ export declare const NudgeSchema: z.ZodObject<{
288
+ trailing30Micro: z.ZodString;
289
+ suggestedPlanId: z.ZodString;
290
+ suggestedPlanDisplayName: z.ZodString;
291
+ suggestedPlanPriceMicro: z.ZodString;
292
+ savingMicro: z.ZodString;
293
+ computedAt: z.ZodISODateTime;
294
+ dismissible: z.ZodLiteral<true>;
295
+ }, z.core.$strip>;
296
+ /** One already-computed comparison. */
297
+ export type Nudge = z.infer<typeof NudgeSchema>;
298
+ /**
299
+ * A request for a hosted page.
300
+ *
301
+ * `skuId` is an identifier the client received from the server. A client never
302
+ * constructs one and never enumerates the set. The amount and its rendering
303
+ * belong to the hosted page, not to this contract.
304
+ */
305
+ export declare const HostedPageRequestSchema: z.ZodObject<{
306
+ skuId: z.ZodOptional<z.ZodString>;
307
+ returnUrl: z.ZodOptional<z.ZodString>;
308
+ }, z.core.$strip>;
309
+ /**
310
+ * The hosted page to open.
311
+ *
312
+ * `POST /v1/checkout`, `POST /v1/topup` and `POST /v1/portal` all answer with
313
+ * this. No origin is baked into this package: the URL is a runtime value.
314
+ */
315
+ export declare const HostedPageResponseSchema: z.ZodObject<{
316
+ url: z.ZodString;
317
+ }, z.core.$strip>;
318
+ /** `GET /v1/statement` query parameters. */
319
+ export declare const StatementQuerySchema: z.ZodObject<{
320
+ period: z.ZodString;
321
+ }, z.core.$strip>;
322
+ /** `GET /v1/statement` — a download link for the caller`s itemised statement. */
323
+ export declare const StatementResponseSchema: z.ZodObject<{
324
+ period: z.ZodString;
325
+ downloadUrl: z.ZodString;
326
+ expiresAt: z.ZodISODateTime;
327
+ }, z.core.$strip>;
328
+ //# sourceMappingURL=billing.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"billing.d.ts","sourceRoot":"","sources":["../src/billing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B;;;;EAItC,CAAC;AAEJ,8FAA8F;AAC9F,eAAO,MAAM,6BAA6B;;;;EAIvC,CAAC;AAEJ,gDAAgD;AAChD,eAAO,MAAM,uBAAuB;;;EAEoB,CAAC;AAEzD;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB;;;;;;;iBASmC,CAAC;AAEvE,yDAAyD;AACzD,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;iBAuBjC,CAAC;AAEJ;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAoB5B,CAAC;AAEJ,wCAAwC;AACxC,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;iBAmBvB,CAAC;AAEJ,oCAAoC;AACpC,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAEpD;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe;;;;EAIzB,CAAC;AAEJ,4CAA4C;AAC5C,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB;;;;;;EAE0C,CAAC;AAExE,kCAAkC;AAClC,eAAO,MAAM,kBAAkB;;;;EAEW,CAAC;AAE3C,wCAAwC;AACxC,eAAO,MAAM,gBAAgB;;;;;;;;iBAM4B,CAAC;AAE1D;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;iBAmBxB,CAAC;AAEJ,6DAA6D;AAC7D,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAYqC,CAAC;AAEtE,2CAA2C;AAC3C,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,6CAA6C;AAC7C,eAAO,MAAM,oBAAoB;;;;;;iBAUoB,CAAC;AAEtD;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;iBAQjC,CAAC;AAEJ;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW;;;;;;;;iBAU2E,CAAC;AAEpG,uCAAuC;AACvC,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEhD;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB;;;iBAW0C,CAAC;AAE/E;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;iBAEyD,CAAC;AAE/F,4CAA4C;AAC5C,eAAO,MAAM,oBAAoB;;iBAI4B,CAAC;AAE9D,iFAAiF;AACjF,eAAO,MAAM,uBAAuB;;;;iBAMqD,CAAC"}