@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.
- package/LICENSE +21 -0
- package/README.md +192 -0
- package/dist/billing.d.ts +328 -0
- package/dist/billing.d.ts.map +1 -0
- package/dist/billing.js +267 -0
- package/dist/billing.js.map +1 -0
- package/dist/client.d.ts +130 -0
- package/dist/client.d.ts.map +1 -0
- package/dist/client.js +192 -0
- package/dist/client.js.map +1 -0
- package/dist/connections.d.ts +281 -0
- package/dist/connections.d.ts.map +1 -0
- package/dist/connections.js +241 -0
- package/dist/connections.js.map +1 -0
- package/dist/index.d.ts +31 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +31 -0
- package/dist/index.js.map +1 -0
- package/dist/inference.d.ts +123 -0
- package/dist/inference.d.ts.map +1 -0
- package/dist/inference.js +114 -0
- package/dist/inference.js.map +1 -0
- package/dist/instances.d.ts +60 -0
- package/dist/instances.d.ts.map +1 -0
- package/dist/instances.js +65 -0
- package/dist/instances.js.map +1 -0
- package/dist/primitives.d.ts +74 -0
- package/dist/primitives.d.ts.map +1 -0
- package/dist/primitives.js +98 -0
- package/dist/primitives.js.map +1 -0
- package/dist/problem.d.ts +96 -0
- package/dist/problem.d.ts.map +1 -0
- package/dist/problem.js +94 -0
- package/dist/problem.js.map +1 -0
- package/dist/remote.d.ts +268 -0
- package/dist/remote.d.ts.map +1 -0
- package/dist/remote.js +267 -0
- package/dist/remote.js.map +1 -0
- package/dist/routes.d.ts +273 -0
- package/dist/routes.d.ts.map +1 -0
- package/dist/routes.js +302 -0
- package/dist/routes.js.map +1 -0
- package/dist/seats.d.ts +529 -0
- package/dist/seats.d.ts.map +1 -0
- package/dist/seats.js +266 -0
- package/dist/seats.js.map +1 -0
- package/dist/session.d.ts +135 -0
- package/dist/session.d.ts.map +1 -0
- package/dist/session.js +143 -0
- package/dist/session.js.map +1 -0
- package/fixtures/v1/billing/balance-owed.json +16 -0
- package/fixtures/v1/billing/balance.json +16 -0
- package/fixtures/v1/billing/entitlements-free.json +34 -0
- package/fixtures/v1/billing/hosted-page.json +3 -0
- package/fixtures/v1/billing/nudge.json +9 -0
- package/fixtures/v1/billing/price-list.json +13 -0
- package/fixtures/v1/billing/statement.json +5 -0
- package/fixtures/v1/billing/usage-by-model.json +21 -0
- package/fixtures/v1/connections/catalog.json +12 -0
- package/fixtures/v1/connections/events-ack.json +3 -0
- package/fixtures/v1/connections/events-pull.json +16 -0
- package/fixtures/v1/connections/execution.json +12 -0
- package/fixtures/v1/connections/list.json +16 -0
- package/fixtures/v1/connections/usage.json +16 -0
- package/fixtures/v1/index.json +58 -0
- package/fixtures/v1/inference/models.json +17 -0
- package/fixtures/v1/inference/token-revoke.json +3 -0
- package/fixtures/v1/inference/token.json +14 -0
- package/fixtures/v1/instances/heartbeat.json +5 -0
- package/fixtures/v1/instances/list.json +15 -0
- package/fixtures/v1/instances/revoke.json +3 -0
- package/fixtures/v1/problem/handle-tombstoned.json +6 -0
- package/fixtures/v1/problem/person-seat-required.json +7 -0
- package/fixtures/v1/problem/unauthenticated.json +7 -0
- package/fixtures/v1/remote/address.json +5 -0
- package/fixtures/v1/remote/command-keepalive.json +4 -0
- package/fixtures/v1/remote/command-open.json +6 -0
- package/fixtures/v1/remote/commands-ack.json +3 -0
- package/fixtures/v1/remote/credential.json +7 -0
- package/fixtures/v1/remote/custom-address.json +12 -0
- package/fixtures/v1/remote/designation.json +5 -0
- package/fixtures/v1/remote/enrolment.json +5 -0
- package/fixtures/v1/remote/events.json +3 -0
- package/fixtures/v1/remote/open.json +5 -0
- package/fixtures/v1/remote/status-closed.json +7 -0
- package/fixtures/v1/remote/status-open.json +10 -0
- package/fixtures/v1/remote/wake-token.json +5 -0
- package/fixtures/v1/seats/addons.json +11 -0
- package/fixtures/v1/seats/agent.json +9 -0
- package/fixtures/v1/seats/grants.json +20 -0
- package/fixtures/v1/seats/inbox-browse.json +17 -0
- package/fixtures/v1/seats/inbox-pull.json +17 -0
- package/fixtures/v1/seats/invitation.json +9 -0
- package/fixtures/v1/seats/members.json +12 -0
- package/fixtures/v1/seats/org.json +7 -0
- package/fixtures/v1/seats/presence.json +6 -0
- package/fixtures/v1/seats/seat.json +21 -0
- package/fixtures/v1/session/account-export.json +6 -0
- package/fixtures/v1/session/device-code.json +8 -0
- package/fixtures/v1/session/device-token-pending.json +4 -0
- package/fixtures/v1/session/device-token.json +7 -0
- package/fixtures/v1/session/signed-in.json +14 -0
- package/fixtures/v1/session/signed-out.json +4 -0
- 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"}
|