@shipstatic/ship 2.0.0-beta.5 → 2.0.0-beta.7
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/dist/browser.d.ts +338 -70
- package/dist/browser.js +1 -1
- package/dist/browser.js.map +1 -1
- package/dist/cli.cjs +25 -26
- package/dist/cli.cjs.map +1 -1
- package/dist/index.cjs +1 -1
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +338 -70
- package/dist/index.d.ts +338 -70
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/package.json +2 -2
package/dist/browser.d.ts
CHANGED
|
@@ -49,14 +49,122 @@ interface DeploymentCreateResponse extends Deployment {
|
|
|
49
49
|
/** Claim URL for public deployments. Present when deployed without credentials. */
|
|
50
50
|
readonly claim?: string;
|
|
51
51
|
}
|
|
52
|
+
/**
|
|
53
|
+
* Every path the public API answers on, declared once.
|
|
54
|
+
*
|
|
55
|
+
* The URL surface was written out in four places — the API's mounts, the
|
|
56
|
+
* SDK's client, the dashboard's client, and the post-deploy smoke — so a
|
|
57
|
+
* rename meant finding all four. The first three now read this table.
|
|
58
|
+
*
|
|
59
|
+
* The smoke (`cloudflare/api/smoke.mjs`) deliberately still spells its own:
|
|
60
|
+
* five of its nine paths are `/admin/*`, which this table excludes by
|
|
61
|
+
* design, and splitting one list between a registry and literals reads worse
|
|
62
|
+
* than keeping it uniform.
|
|
63
|
+
*
|
|
64
|
+
* **What this guarantees, exactly.** Collection paths are mounted from here,
|
|
65
|
+
* so producer and consumer cannot diverge. Item paths are declared here and
|
|
66
|
+
* consumed by clients, but the API spells them relative to their mount
|
|
67
|
+
* (`/:deployment/config`), so the table does not *generate* them — it is
|
|
68
|
+
* held to them by `api/tests/architecture/api-paths.test.ts`, which fails if
|
|
69
|
+
* any entry names a path no route answers. Some entries have no client yet
|
|
70
|
+
* (`DEPLOYMENT_CONFIG`, `DOMAIN_PROPAGATION` — endpoints the SDK
|
|
71
|
+
* deliberately does not reach); the fence is what keeps those honest rather
|
|
72
|
+
* than merely asserted.
|
|
73
|
+
*
|
|
74
|
+
* **The operator surface is deliberately absent.** `/admin/*` paths belong
|
|
75
|
+
* to `web/my`, for the same reason its row types do: this package is
|
|
76
|
+
* published, and the operator surface is not public (see `CLAUDE.md`, "Admin
|
|
77
|
+
* types"). A path here is a promise to every npm consumer; `/admin` is a
|
|
78
|
+
* promise to one dashboard.
|
|
79
|
+
*
|
|
80
|
+
* Item paths are functions rather than templates so the key is interpolated
|
|
81
|
+
* in one place, encoded the same way by every caller.
|
|
82
|
+
*/
|
|
83
|
+
declare const API_PATHS: {
|
|
84
|
+
readonly DEPLOYMENTS: "/deployments";
|
|
85
|
+
readonly DEPLOYMENT: (deployment: string) => string;
|
|
86
|
+
readonly DEPLOYMENT_CONFIG: (deployment: string) => string;
|
|
87
|
+
readonly DOMAINS: "/domains";
|
|
88
|
+
readonly DOMAIN: (domain: string) => string;
|
|
89
|
+
readonly DOMAIN_VERIFY: (domain: string) => string;
|
|
90
|
+
readonly DOMAIN_DNS: (domain: string) => string;
|
|
91
|
+
readonly DOMAIN_RECORDS: (domain: string) => string;
|
|
92
|
+
readonly DOMAIN_SHARE: (domain: string) => string;
|
|
93
|
+
readonly DOMAIN_PROPAGATION: (domain: string) => string;
|
|
94
|
+
readonly DOMAINS_VALIDATE: "/domains/validate";
|
|
95
|
+
readonly TOKENS: "/tokens";
|
|
96
|
+
readonly TOKEN: (token: string) => string;
|
|
97
|
+
readonly ACCOUNT: "/account";
|
|
98
|
+
readonly ACCOUNT_KEY: "/account/key";
|
|
99
|
+
readonly ACCOUNT_CLAIM: "/account/claim";
|
|
100
|
+
readonly ACTIVITIES: "/activities";
|
|
101
|
+
readonly LABELS: "/labels";
|
|
102
|
+
readonly LIMITS: "/limits";
|
|
103
|
+
readonly PING: "/ping";
|
|
104
|
+
readonly SETUP: "/setup";
|
|
105
|
+
readonly SPA_CHECK: "/spa-check";
|
|
106
|
+
readonly UPLOAD: "/upload";
|
|
107
|
+
};
|
|
108
|
+
/**
|
|
109
|
+
* The half of a list response that is identical on every list.
|
|
110
|
+
*
|
|
111
|
+
* `GET /<collection>` answers exactly two fields — the collection under its
|
|
112
|
+
* own plural noun, and this cursor — so the cursor is declared once here and
|
|
113
|
+
* each response below adds only its noun. `cursor: null` means last page and
|
|
114
|
+
* is the ENTIRE has-more signal, which is why there is no `has_more`.
|
|
115
|
+
*
|
|
116
|
+
* There is deliberately no `total`. A count is an aggregate over a
|
|
117
|
+
* collection, not a property of a page; producing one would cost a COUNT
|
|
118
|
+
* beside every page read, which is precisely what keyset pagination exists
|
|
119
|
+
* to avoid. Counts live on the resource that summarises the collection —
|
|
120
|
+
* `GET /account`'s `usage` for one caller, `GET /admin/stats` platform-wide.
|
|
121
|
+
*/
|
|
122
|
+
interface ListResponse {
|
|
123
|
+
/** Opaque cursor from this page; `null` on the last page. */
|
|
124
|
+
cursor: string | null;
|
|
125
|
+
}
|
|
52
126
|
/**
|
|
53
127
|
* Response for listing deployments
|
|
54
128
|
*/
|
|
55
|
-
interface DeploymentListResponse {
|
|
129
|
+
interface DeploymentListResponse extends ListResponse {
|
|
56
130
|
/** Array of deployments */
|
|
57
131
|
deployments: Deployment[];
|
|
58
|
-
|
|
59
|
-
|
|
132
|
+
}
|
|
133
|
+
/**
|
|
134
|
+
* Acknowledgement of `DELETE /deployments/:deployment` — and the shape every
|
|
135
|
+
* mutation with no entity left to return follows.
|
|
136
|
+
*
|
|
137
|
+
* **The law:** a mutation answers with the resource it affected. If the
|
|
138
|
+
* resource still exists, that means the entity itself (`Deployment`,
|
|
139
|
+
* `Domain`, …). Otherwise it means this: the resource noun carrying the
|
|
140
|
+
* item's canonical key, plus the resource's own state field — and ONLY when
|
|
141
|
+
* the resource survived in a transitional state, as an async deletion's does.
|
|
142
|
+
* Where the resource is simply gone, the key alone is the whole answer
|
|
143
|
+
* ({@link DomainDeleteResponse}, {@link TokenDeleteResponse}).
|
|
144
|
+
*
|
|
145
|
+
* Put positively: **an acknowledgement is a projection of the resource** —
|
|
146
|
+
* its key, plus its own state field where the state changed. That is the
|
|
147
|
+
* test to apply, and it is sharper than "no constant", which this shape
|
|
148
|
+
* would fail on its own terms: `status` here is the literal `'deleting'` on
|
|
149
|
+
* every success, exactly as fixed as a `changed: true` would be.
|
|
150
|
+
*
|
|
151
|
+
* The difference is not how predictable the value is, it is what the field
|
|
152
|
+
* IS. `status` is the deployment's own field — the same one `GET
|
|
153
|
+
* /deployments/:deployment` returns — so this response is `Deployment`
|
|
154
|
+
* narrowed to two members, and a client renders it with the code it already
|
|
155
|
+
* has. `changed: true`, `queued: true` and `success: true` are not fields of
|
|
156
|
+
* any entity; they exist only to assert that the call worked, which the
|
|
157
|
+
* status code already said. Sync versus accepted is likewise the status
|
|
158
|
+
* code's job — 200 versus 202 — not a boolean's.
|
|
159
|
+
*
|
|
160
|
+
* No prose either (`message`): an acknowledgement is data, and each surface
|
|
161
|
+
* composes its own copy.
|
|
162
|
+
*/
|
|
163
|
+
interface DeploymentDeleteResponse {
|
|
164
|
+
/** The deployment hostname that was marked for removal */
|
|
165
|
+
readonly deployment: string;
|
|
166
|
+
/** The state the deployment is in while background cleanup runs */
|
|
167
|
+
readonly status: DeploymentStatusType;
|
|
60
168
|
}
|
|
61
169
|
/**
|
|
62
170
|
* Domain status constants
|
|
@@ -89,7 +197,7 @@ interface Domain {
|
|
|
89
197
|
labels: string[];
|
|
90
198
|
/** Unix timestamp (seconds) when domain was created */
|
|
91
199
|
readonly created: number;
|
|
92
|
-
/**
|
|
200
|
+
/** Unix timestamp (seconds) when deployment was last linked, null if never linked */
|
|
93
201
|
linked: number | null;
|
|
94
202
|
/** Total deployment links */
|
|
95
203
|
links: number;
|
|
@@ -111,11 +219,28 @@ interface DomainSetResult extends Domain {
|
|
|
111
219
|
/**
|
|
112
220
|
* Response for listing domains
|
|
113
221
|
*/
|
|
114
|
-
interface DomainListResponse {
|
|
222
|
+
interface DomainListResponse extends ListResponse {
|
|
115
223
|
/** Array of domains */
|
|
116
224
|
domains: Domain[];
|
|
117
|
-
|
|
118
|
-
|
|
225
|
+
}
|
|
226
|
+
/**
|
|
227
|
+
* Acknowledgement of `DELETE /domains/:domain`. The row is gone, so there is
|
|
228
|
+
* no state to state — the canonical domain name is the whole answer. See
|
|
229
|
+
* {@link DeploymentDeleteResponse} for the law.
|
|
230
|
+
*/
|
|
231
|
+
interface DomainDeleteResponse {
|
|
232
|
+
/** The domain name that was removed, normalized */
|
|
233
|
+
readonly domain: string;
|
|
234
|
+
}
|
|
235
|
+
/**
|
|
236
|
+
* Acknowledgement of `POST /domains/:domain/verify` (202). The DNS check is
|
|
237
|
+
* queued, not performed — the accepted status code says so, and the domain's
|
|
238
|
+
* own status is unchanged until the check runs, which is why none is stated
|
|
239
|
+
* here. See {@link DeploymentDeleteResponse} for the law.
|
|
240
|
+
*/
|
|
241
|
+
interface DomainVerifyResponse {
|
|
242
|
+
/** The domain whose DNS verification was queued, normalized */
|
|
243
|
+
readonly domain: string;
|
|
119
244
|
}
|
|
120
245
|
/**
|
|
121
246
|
* DNS record types supported for domain configuration
|
|
@@ -142,13 +267,33 @@ interface DnsProvider {
|
|
|
142
267
|
/**
|
|
143
268
|
* Response for domain DNS provider lookup
|
|
144
269
|
*/
|
|
270
|
+
/**
|
|
271
|
+
* What a DNS lookup found for a domain. An envelope rather than a bare
|
|
272
|
+
* {@link DnsProvider} because a lookup can succeed and learn more than the
|
|
273
|
+
* provider later; the shape is named so a consumer can hold one.
|
|
274
|
+
*/
|
|
275
|
+
interface DnsLookup {
|
|
276
|
+
/** The provider serving this domain's DNS, absent when unidentified */
|
|
277
|
+
provider?: DnsProvider;
|
|
278
|
+
}
|
|
145
279
|
interface DomainDnsResponse {
|
|
146
280
|
/** The domain name */
|
|
147
281
|
domain: string;
|
|
148
282
|
/** DNS provider information, null if not yet looked up */
|
|
149
|
-
dns:
|
|
150
|
-
|
|
151
|
-
|
|
283
|
+
dns: DnsLookup | null;
|
|
284
|
+
}
|
|
285
|
+
/**
|
|
286
|
+
* Response for `GET /domains/:domain/share` — the domain plus the salted
|
|
287
|
+
* hash that lets someone else complete its DNS setup without an account.
|
|
288
|
+
*
|
|
289
|
+
* `/admin/domains/:domain/share` answers the same shape, which is the admin
|
|
290
|
+
* law working: the operator surface is the public grammar with a prefix.
|
|
291
|
+
*/
|
|
292
|
+
interface DomainShareResponse {
|
|
293
|
+
/** The domain the setup link is for */
|
|
294
|
+
readonly domain: string;
|
|
295
|
+
/** The salted setup hash that authorizes the share */
|
|
296
|
+
readonly hash: string;
|
|
152
297
|
}
|
|
153
298
|
/**
|
|
154
299
|
* Response for domain DNS records
|
|
@@ -161,6 +306,53 @@ interface DomainRecordsResponse {
|
|
|
161
306
|
/** Required DNS records for configuration */
|
|
162
307
|
records: DnsRecord[];
|
|
163
308
|
}
|
|
309
|
+
/**
|
|
310
|
+
* The envelope an `Idempotency-Key` must fit, and how long a replay lasts.
|
|
311
|
+
*
|
|
312
|
+
* Format lives here rather than on the server alone by the format-vs-policy
|
|
313
|
+
* rule: a client can decide offline whether a key is well-formed, and the
|
|
314
|
+
* API would reject the same value the same way.
|
|
315
|
+
*/
|
|
316
|
+
declare const IDEMPOTENCY_KEY_CONSTRAINTS: {
|
|
317
|
+
readonly MAX_LENGTH: 256;
|
|
318
|
+
/** How long a stored 201 stays replayable. */
|
|
319
|
+
readonly WINDOW_SECONDS: number;
|
|
320
|
+
};
|
|
321
|
+
/**
|
|
322
|
+
* Validate an idempotency key, returning the trimmed value or `undefined`
|
|
323
|
+
* when none was supplied. Throws {@link ShipError.validation} when the value
|
|
324
|
+
* cannot be sent — the same verdict the API would reach, reached earlier.
|
|
325
|
+
*/
|
|
326
|
+
declare function validateIdempotencyKey(value: unknown): string | undefined;
|
|
327
|
+
/**
|
|
328
|
+
* Response for `GET /labels` — every label in use across the caller's
|
|
329
|
+
* deployments, domains and tokens, grouped and ordered by last use.
|
|
330
|
+
*
|
|
331
|
+
* The one plural noun outside the list contract, deliberately: labels have
|
|
332
|
+
* no identity, no row and no `created`, so there is nothing for a keyset
|
|
333
|
+
* cursor to resume after, and its consumer is an autocomplete that wants the
|
|
334
|
+
* whole set. Bounded by `PAGINATION.GLOBAL_LIMIT` rather than paginated.
|
|
335
|
+
*/
|
|
336
|
+
interface LabelsResponse {
|
|
337
|
+
readonly labels: string[];
|
|
338
|
+
}
|
|
339
|
+
/**
|
|
340
|
+
* Response for `POST /setup` — the DNS instructions for one domain, written
|
|
341
|
+
* for a human to follow at their registrar.
|
|
342
|
+
*
|
|
343
|
+
* `custom` is the provider-specific walkthrough when the provider is known;
|
|
344
|
+
* `generic` always answers, so a caller never has nothing to show.
|
|
345
|
+
*/
|
|
346
|
+
interface SetupInstructionsResponse {
|
|
347
|
+
/** One-line summary of what to do */
|
|
348
|
+
readonly tldr: string;
|
|
349
|
+
/** Provider-specific instructions, null when the provider is unknown */
|
|
350
|
+
readonly custom: string | null;
|
|
351
|
+
/** Provider-agnostic instructions — always present */
|
|
352
|
+
readonly generic: string;
|
|
353
|
+
/** The identified DNS provider, null when unknown */
|
|
354
|
+
readonly provider: string | null;
|
|
355
|
+
}
|
|
164
356
|
/**
|
|
165
357
|
* Response for domain validation
|
|
166
358
|
*/
|
|
@@ -175,11 +367,13 @@ interface DomainValidateResponse {
|
|
|
175
367
|
error: string | null;
|
|
176
368
|
}
|
|
177
369
|
/**
|
|
178
|
-
*
|
|
179
|
-
*
|
|
180
|
-
*
|
|
370
|
+
* Core deploy token object - used in both API responses and SDK.
|
|
371
|
+
*
|
|
372
|
+
* The secret is never here: it is shown once at creation
|
|
373
|
+
* ({@link TokenCreateResponse.secret}) and never again, so an entity read
|
|
374
|
+
* carries only the management identifier and lifecycle metadata.
|
|
181
375
|
*/
|
|
182
|
-
interface
|
|
376
|
+
interface Token {
|
|
183
377
|
/** 7-char management identifier (e.g., "a1b2c3d") */
|
|
184
378
|
readonly token: string;
|
|
185
379
|
/** Labels for categorization and filtering. Always present, empty array when none. */
|
|
@@ -194,24 +388,28 @@ interface TokenListItem {
|
|
|
194
388
|
/**
|
|
195
389
|
* Response for listing tokens
|
|
196
390
|
*/
|
|
197
|
-
interface TokenListResponse {
|
|
198
|
-
/** Array of tokens (
|
|
199
|
-
tokens:
|
|
200
|
-
/** Cursor for pagination, null if no more pages */
|
|
201
|
-
cursor: string | null;
|
|
391
|
+
interface TokenListResponse extends ListResponse {
|
|
392
|
+
/** Array of tokens (the secret is never among them) */
|
|
393
|
+
tokens: Token[];
|
|
202
394
|
}
|
|
203
395
|
/**
|
|
204
|
-
* Response
|
|
396
|
+
* Response from token creation. Extends Token with the one field that
|
|
397
|
+
* exists only on creation — the same shape as
|
|
398
|
+
* {@link DeploymentCreateResponse}, because a 201 returns the resource it
|
|
399
|
+
* created plus whatever is knowable only once.
|
|
205
400
|
*/
|
|
206
|
-
interface TokenCreateResponse {
|
|
207
|
-
/** 7-char management identifier */
|
|
208
|
-
token: string;
|
|
401
|
+
interface TokenCreateResponse extends Token {
|
|
209
402
|
/** The raw credential value (shown once at creation, then never again) */
|
|
210
|
-
secret: string;
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
403
|
+
readonly secret: string;
|
|
404
|
+
}
|
|
405
|
+
/**
|
|
406
|
+
* Acknowledgement of `DELETE /tokens/:token`. The credential is revoked and
|
|
407
|
+
* its row is gone, so the management identifier is the whole answer. See
|
|
408
|
+
* {@link DeploymentDeleteResponse} for the law.
|
|
409
|
+
*/
|
|
410
|
+
interface TokenDeleteResponse {
|
|
411
|
+
/** The 7-char management identifier that was revoked */
|
|
412
|
+
readonly token: string;
|
|
215
413
|
}
|
|
216
414
|
/**
|
|
217
415
|
* Account plan constants
|
|
@@ -302,6 +500,32 @@ interface AccountGetResponse extends Account {
|
|
|
302
500
|
/** Present only during read-only admin impersonation: the operator's account id. */
|
|
303
501
|
readonly impersonatedBy?: string;
|
|
304
502
|
}
|
|
503
|
+
/**
|
|
504
|
+
* Acknowledgement of `DELETE /account` (202). Termination is asynchronous —
|
|
505
|
+
* a cleanup consumer finishes the job — so the account survives long enough
|
|
506
|
+
* to state the plan it is transitioning through. `plan` is the account's
|
|
507
|
+
* state field, the way `status` is a deployment's. See
|
|
508
|
+
* {@link DeploymentDeleteResponse} for the law.
|
|
509
|
+
*/
|
|
510
|
+
interface AccountDeleteResponse {
|
|
511
|
+
/** The account that was marked for termination */
|
|
512
|
+
readonly account: string;
|
|
513
|
+
/** The plan the account is in while cleanup runs */
|
|
514
|
+
readonly plan: AccountPlanType;
|
|
515
|
+
}
|
|
516
|
+
/**
|
|
517
|
+
* Response from `PUT /account/key` — the account's single API key, minted in
|
|
518
|
+
* place of whatever was there before.
|
|
519
|
+
*
|
|
520
|
+
* There is no entity to return: only the key's last-4 `hint` is durable
|
|
521
|
+
* (`Account.hint`), and the plaintext exists exactly once, in this response.
|
|
522
|
+
* The raw credential is `secret` on every surface that mints one — the same
|
|
523
|
+
* field `TokenCreateResponse` carries — because one concept gets one name.
|
|
524
|
+
*/
|
|
525
|
+
interface AccountKeyResponse {
|
|
526
|
+
/** The raw API key (shown once at mint, then never again) */
|
|
527
|
+
readonly secret: string;
|
|
528
|
+
}
|
|
305
529
|
/**
|
|
306
530
|
* Account-specific configuration overrides
|
|
307
531
|
* Allows per-account customization of limits without changing plan
|
|
@@ -328,7 +552,15 @@ interface AccountOverrides {
|
|
|
328
552
|
* (`DeploymentStatus`, `DomainStatus`, `AccountPlan`, `AuthMethod`) follow.
|
|
329
553
|
*/
|
|
330
554
|
declare const ErrorType: {
|
|
331
|
-
/**
|
|
555
|
+
/**
|
|
556
|
+
* Validation failed. Input shape is wrong.
|
|
557
|
+
*
|
|
558
|
+
* Carries 400 when an API judged it — including a client-side pre-check of a
|
|
559
|
+
* rule the server enforces too, which keeps the error identical wherever it
|
|
560
|
+
* was caught. **Statusless** when a client rejects something no API judges,
|
|
561
|
+
* such as a CLI's own command grammar: `status` is documented "(API
|
|
562
|
+
* contexts)" on `ErrorResponse`, so there is none to report.
|
|
563
|
+
*/
|
|
332
564
|
readonly Validation: "validation_failed";
|
|
333
565
|
/** Resource not found (404). */
|
|
334
566
|
readonly NotFound: "not_found";
|
|
@@ -749,16 +981,22 @@ interface SPACheckRequest {
|
|
|
749
981
|
/**
|
|
750
982
|
* Response from SPA check endpoint
|
|
751
983
|
*/
|
|
984
|
+
/**
|
|
985
|
+
* Which of the classifier's tiers reached the verdict, and why. Named rather
|
|
986
|
+
* than inline so the API's own `checkSPA` can return `SPACheckResponse`
|
|
987
|
+
* instead of restating its shape.
|
|
988
|
+
*/
|
|
989
|
+
interface SPACheckDebug {
|
|
990
|
+
/** Which tier made the detection */
|
|
991
|
+
tier: 'exclusions' | 'inclusions' | 'scoring' | 'ai' | 'fallback';
|
|
992
|
+
/** The reason for the detection result */
|
|
993
|
+
reason: string;
|
|
994
|
+
}
|
|
752
995
|
interface SPACheckResponse {
|
|
753
996
|
/** Whether the project is detected as a Single Page Application */
|
|
754
997
|
isSPA: boolean;
|
|
755
998
|
/** Debugging information about detection */
|
|
756
|
-
debug:
|
|
757
|
-
/** Which tier made the detection: 'exclusions', 'inclusions', 'scoring', 'ai', or 'fallback' */
|
|
758
|
-
tier: 'exclusions' | 'inclusions' | 'scoring' | 'ai' | 'fallback';
|
|
759
|
-
/** The reason for the detection result */
|
|
760
|
-
reason: string;
|
|
761
|
-
};
|
|
999
|
+
debug: SPACheckDebug;
|
|
762
1000
|
}
|
|
763
1001
|
/**
|
|
764
1002
|
* Represents a file that has been processed and is ready for deploy.
|
|
@@ -830,6 +1068,25 @@ interface DeploymentUploadOptions {
|
|
|
830
1068
|
spa?: boolean;
|
|
831
1069
|
/** @internal reCAPTCHA proof for the anonymous human deploy channel. Only available via /upload endpoint. */
|
|
832
1070
|
captcha?: string;
|
|
1071
|
+
/**
|
|
1072
|
+
* Makes this deploy replayable instead of repeatable.
|
|
1073
|
+
*
|
|
1074
|
+
* A deploy is not naturally idempotent: a client-side timeout on a slow
|
|
1075
|
+
* one leaves the caller unable to tell "it never landed" from "it landed
|
|
1076
|
+
* and the response was lost", and retrying produces a second deployment.
|
|
1077
|
+
* Send the same key on the retry and the platform replays the original
|
|
1078
|
+
* 201 verbatim rather than creating anything
|
|
1079
|
+
* ({@link IDEMPOTENCY_KEY_CONSTRAINTS.WINDOW_SECONDS}).
|
|
1080
|
+
*
|
|
1081
|
+
* **Agents are the audience.** A human notices a duplicate; an automated
|
|
1082
|
+
* retry does not. Pick a key that identifies the ATTEMPT — a run id, a
|
|
1083
|
+
* commit sha, a uuid minted before the first try — never one that varies
|
|
1084
|
+
* per attempt, which would defeat the point.
|
|
1085
|
+
*
|
|
1086
|
+
* The replay is per-caller, and it stores successes only: a failed deploy
|
|
1087
|
+
* retries fresh under the same key.
|
|
1088
|
+
*/
|
|
1089
|
+
idempotencyKey?: string;
|
|
833
1090
|
}
|
|
834
1091
|
/**
|
|
835
1092
|
* Pagination options for every list endpoint. The response's `cursor` feeds
|
|
@@ -853,6 +1110,33 @@ interface ListOptions {
|
|
|
853
1110
|
/** Opaque cursor from the previous page's response. */
|
|
854
1111
|
cursor?: string;
|
|
855
1112
|
}
|
|
1113
|
+
/**
|
|
1114
|
+
* What a caller may change on an existing deployment.
|
|
1115
|
+
*
|
|
1116
|
+
* Labels and nothing else: a deployment's content is immutable by design, so
|
|
1117
|
+
* this is the whole mutable surface rather than a subset someone chose.
|
|
1118
|
+
*/
|
|
1119
|
+
interface DeploymentSetOptions {
|
|
1120
|
+
labels: string[];
|
|
1121
|
+
}
|
|
1122
|
+
/**
|
|
1123
|
+
* What `domains.set()` may create or change. Every field is optional because
|
|
1124
|
+
* the call is a natural-key upsert: omitting `deployment` reserves the
|
|
1125
|
+
* domain, naming one links or re-points it, and labels travel either way.
|
|
1126
|
+
*
|
|
1127
|
+
* `deployment` is deliberately not nullable — unlinking is refused (400).
|
|
1128
|
+
* See `npm/ship/CLAUDE.md`, "Domain Write Semantics".
|
|
1129
|
+
*/
|
|
1130
|
+
interface DomainSetOptions {
|
|
1131
|
+
deployment?: string;
|
|
1132
|
+
labels?: string[];
|
|
1133
|
+
}
|
|
1134
|
+
/** What a caller may set when minting a deploy token. */
|
|
1135
|
+
interface TokenCreateOptions {
|
|
1136
|
+
/** Seconds until expiry; omit for a token that never expires. */
|
|
1137
|
+
ttl?: number;
|
|
1138
|
+
labels?: string[];
|
|
1139
|
+
}
|
|
856
1140
|
/**
|
|
857
1141
|
* Deployment resource interface - the contract all implementations must follow.
|
|
858
1142
|
*
|
|
@@ -865,32 +1149,22 @@ interface DeploymentResource<UploadOptions extends DeploymentUploadOptions = Dep
|
|
|
865
1149
|
upload: (input: DeployInput, options?: UploadOptions) => Promise<DeploymentCreateResponse>;
|
|
866
1150
|
list: (options?: ListOptions) => Promise<DeploymentListResponse>;
|
|
867
1151
|
get: (id: string) => Promise<Deployment>;
|
|
868
|
-
set: (id: string, options:
|
|
869
|
-
|
|
870
|
-
}) => Promise<Deployment>;
|
|
871
|
-
remove: (id: string) => Promise<void>;
|
|
1152
|
+
set: (id: string, options: DeploymentSetOptions) => Promise<Deployment>;
|
|
1153
|
+
remove: (id: string) => Promise<DeploymentDeleteResponse>;
|
|
872
1154
|
}
|
|
873
1155
|
/**
|
|
874
1156
|
* Domain resource interface - the contract all implementations must follow
|
|
875
1157
|
*/
|
|
876
1158
|
interface DomainResource {
|
|
877
|
-
set: (name: string, options?:
|
|
878
|
-
deployment?: string;
|
|
879
|
-
labels?: string[];
|
|
880
|
-
}) => Promise<DomainSetResult>;
|
|
1159
|
+
set: (name: string, options?: DomainSetOptions) => Promise<DomainSetResult>;
|
|
881
1160
|
list: (options?: ListOptions) => Promise<DomainListResponse>;
|
|
882
1161
|
get: (name: string) => Promise<Domain>;
|
|
883
|
-
remove: (name: string) => Promise<
|
|
884
|
-
verify: (name: string) => Promise<
|
|
885
|
-
message: string;
|
|
886
|
-
}>;
|
|
1162
|
+
remove: (name: string) => Promise<DomainDeleteResponse>;
|
|
1163
|
+
verify: (name: string) => Promise<DomainVerifyResponse>;
|
|
887
1164
|
validate: (name: string) => Promise<DomainValidateResponse>;
|
|
888
1165
|
dns: (name: string) => Promise<DomainDnsResponse>;
|
|
889
1166
|
records: (name: string) => Promise<DomainRecordsResponse>;
|
|
890
|
-
share: (name: string) => Promise<
|
|
891
|
-
domain: string;
|
|
892
|
-
hash: string;
|
|
893
|
-
}>;
|
|
1167
|
+
share: (name: string) => Promise<DomainShareResponse>;
|
|
894
1168
|
}
|
|
895
1169
|
/**
|
|
896
1170
|
* Account resource interface - the contract all implementations must follow
|
|
@@ -902,12 +1176,10 @@ interface AccountResource {
|
|
|
902
1176
|
* Token resource interface - the contract all implementations must follow
|
|
903
1177
|
*/
|
|
904
1178
|
interface TokenResource {
|
|
905
|
-
create: (options?:
|
|
906
|
-
ttl?: number;
|
|
907
|
-
labels?: string[];
|
|
908
|
-
}) => Promise<TokenCreateResponse>;
|
|
1179
|
+
create: (options?: TokenCreateOptions) => Promise<TokenCreateResponse>;
|
|
909
1180
|
list: (options?: ListOptions) => Promise<TokenListResponse>;
|
|
910
|
-
|
|
1181
|
+
get: (token: string) => Promise<Token>;
|
|
1182
|
+
remove: (token: string) => Promise<TokenDeleteResponse>;
|
|
911
1183
|
}
|
|
912
1184
|
/**
|
|
913
1185
|
* Billing status response from GET /billing/status
|
|
@@ -1001,11 +1273,9 @@ interface ActivityMeta {
|
|
|
1001
1273
|
/**
|
|
1002
1274
|
* Response from GET /activities endpoint
|
|
1003
1275
|
*/
|
|
1004
|
-
interface ActivityListResponse {
|
|
1276
|
+
interface ActivityListResponse extends ListResponse {
|
|
1005
1277
|
/** Array of activities */
|
|
1006
1278
|
activities: Activity[];
|
|
1007
|
-
/** Cursor for pagination, null if no more pages */
|
|
1008
|
-
cursor: string | null;
|
|
1009
1279
|
}
|
|
1010
1280
|
/**
|
|
1011
1281
|
* File status constants for validation state tracking
|
|
@@ -1421,6 +1691,8 @@ declare class ApiHttp extends SimpleEvents {
|
|
|
1421
1691
|
private readonly session;
|
|
1422
1692
|
private readonly caller;
|
|
1423
1693
|
private readonly timeout;
|
|
1694
|
+
private readonly deployTimeout;
|
|
1695
|
+
private readonly deployBuildTimeout;
|
|
1424
1696
|
private readonly fetch;
|
|
1425
1697
|
private readonly createDeployBody;
|
|
1426
1698
|
private readonly deployEndpoint;
|
|
@@ -1451,24 +1723,20 @@ declare class ApiHttp extends SimpleEvents {
|
|
|
1451
1723
|
listDeployments(options?: ListOptions): Promise<DeploymentListResponse>;
|
|
1452
1724
|
getDeployment(id: string): Promise<Deployment>;
|
|
1453
1725
|
updateDeploymentLabels(id: string, labels: string[]): Promise<Deployment>;
|
|
1454
|
-
removeDeployment(id: string): Promise<
|
|
1726
|
+
removeDeployment(id: string): Promise<DeploymentDeleteResponse>;
|
|
1455
1727
|
setDomain(name: string, deployment?: string, labels?: string[]): Promise<DomainSetResult>;
|
|
1456
1728
|
listDomains(options?: ListOptions): Promise<DomainListResponse>;
|
|
1457
1729
|
getDomain(name: string): Promise<Domain>;
|
|
1458
|
-
removeDomain(name: string): Promise<
|
|
1459
|
-
verifyDomain(name: string): Promise<
|
|
1460
|
-
message: string;
|
|
1461
|
-
}>;
|
|
1730
|
+
removeDomain(name: string): Promise<DomainDeleteResponse>;
|
|
1731
|
+
verifyDomain(name: string): Promise<DomainVerifyResponse>;
|
|
1462
1732
|
getDomainDns(name: string): Promise<DomainDnsResponse>;
|
|
1463
1733
|
getDomainRecords(name: string): Promise<DomainRecordsResponse>;
|
|
1464
|
-
getDomainShare(name: string): Promise<
|
|
1465
|
-
domain: string;
|
|
1466
|
-
hash: string;
|
|
1467
|
-
}>;
|
|
1734
|
+
getDomainShare(name: string): Promise<DomainShareResponse>;
|
|
1468
1735
|
validateDomain(name: string): Promise<DomainValidateResponse>;
|
|
1469
1736
|
createToken(ttl?: number, labels?: string[]): Promise<TokenCreateResponse>;
|
|
1470
1737
|
listTokens(options?: ListOptions): Promise<TokenListResponse>;
|
|
1471
|
-
removeToken(token: string): Promise<
|
|
1738
|
+
removeToken(token: string): Promise<TokenDeleteResponse>;
|
|
1739
|
+
getToken(token: string): Promise<Token>;
|
|
1472
1740
|
getAccount(): Promise<AccountGetResponse>;
|
|
1473
1741
|
getLimits(): Promise<PlatformLimits>;
|
|
1474
1742
|
ping(): Promise<boolean>;
|
|
@@ -1902,4 +2170,4 @@ declare class Ship extends Ship$1 {
|
|
|
1902
2170
|
protected getDeployBodyCreator(): DeployBodyCreator;
|
|
1903
2171
|
}
|
|
1904
2172
|
|
|
1905
|
-
export { API_KEY, AUTH_BASE_PATH, type Account, type AccountGetResponse, type AccountOverrides, AccountPlan, type AccountPlanType, type AccountResource, type AccountUsage, type Activity, type ActivityEvent, type ActivityListResponse, type ActivityMeta, type ApiDeployOptions, ApiHttp, type ApiHttpOptions, AuthMethod, type AuthMethodType, BLOCKED_EXTENSIONS, type BillingStatus, CALLER, type CheckoutSession, DEFAULT_API, DEPLOYMENT_CONFIG_FILENAME, DEPLOY_TOKEN, type DeployBody, type DeployBodyContext, type DeployBodyCreator, type DeployFile, type DeployInput, type Deployment, type DeploymentCreateResponse, type DeploymentListResponse, type DeploymentOptions, type DeploymentResource, type DeploymentResourceContext, DeploymentStatus, type DeploymentStatusType, type DeploymentUploadOptions, type DnsProvider, type DnsRecord, type DnsRecordType, type Domain, type DomainDnsResponse, type DomainListResponse, type DomainRecordsResponse, type DomainResource, type DomainSetResult, DomainStatus, type DomainStatusType, type DomainValidateResponse, type ErrorResponse, ErrorType, type ExecutionEnvironment, FileValidationStatus as FILE_VALIDATION_STATUS, type Fetch, type FileValidationResult, FileValidationStatus, type FileValidationStatusType, JUNK_DIRECTORIES, LABEL_CONSTRAINTS, LABEL_PATTERN, type ListOptions, type MD5Result, OAuthScope, type OAuthScopeType, PASSWORD_CONSTRAINTS, type PingResponse, type PlatformLimits, type ResourceContext, type SPACheckRequest, type SPACheckResponse, SPA_DEFAULT_CONFIG, Ship, type ShipClientOptions, ShipError, type ShipEvents, type StaticFile, type
|
|
2173
|
+
export { API_KEY, API_PATHS, AUTH_BASE_PATH, type Account, type AccountDeleteResponse, type AccountGetResponse, type AccountKeyResponse, type AccountOverrides, AccountPlan, type AccountPlanType, type AccountResource, type AccountUsage, type Activity, type ActivityEvent, type ActivityListResponse, type ActivityMeta, type ApiDeployOptions, ApiHttp, type ApiHttpOptions, AuthMethod, type AuthMethodType, BLOCKED_EXTENSIONS, type BillingStatus, CALLER, type CheckoutSession, DEFAULT_API, DEPLOYMENT_CONFIG_FILENAME, DEPLOY_TOKEN, type DeployBody, type DeployBodyContext, type DeployBodyCreator, type DeployFile, type DeployInput, type Deployment, type DeploymentCreateResponse, type DeploymentDeleteResponse, type DeploymentListResponse, type DeploymentOptions, type DeploymentResource, type DeploymentResourceContext, type DeploymentSetOptions, DeploymentStatus, type DeploymentStatusType, type DeploymentUploadOptions, type DnsLookup, type DnsProvider, type DnsRecord, type DnsRecordType, type Domain, type DomainDeleteResponse, type DomainDnsResponse, type DomainListResponse, type DomainRecordsResponse, type DomainResource, type DomainSetOptions, type DomainSetResult, type DomainShareResponse, DomainStatus, type DomainStatusType, type DomainValidateResponse, type DomainVerifyResponse, type ErrorResponse, ErrorType, type ExecutionEnvironment, FileValidationStatus as FILE_VALIDATION_STATUS, type Fetch, type FileValidationResult, FileValidationStatus, type FileValidationStatusType, IDEMPOTENCY_KEY_CONSTRAINTS, JUNK_DIRECTORIES, LABEL_CONSTRAINTS, LABEL_PATTERN, type LabelsResponse, type ListOptions, type ListResponse, type MD5Result, OAuthScope, type OAuthScopeType, PASSWORD_CONSTRAINTS, type PingResponse, type PlatformLimits, type ResourceContext, type SPACheckDebug, type SPACheckRequest, type SPACheckResponse, SPA_DEFAULT_CONFIG, type SetupInstructionsResponse, Ship, type ShipClientOptions, ShipError, type ShipEvents, type StaticFile, type Token, type TokenCreateOptions, type TokenCreateResponse, type TokenDeleteResponse, TokenKind, type TokenKindType, type TokenListResponse, type TokenProvider, type TokenResource, UNBUILT_PROJECT_MARKERS, UNSAFE_FILENAME_CHARS, type UploadedFile, type UserVisibleActivityEvent, type ValidatableFile, type ValidationIssue, __setTestEnvironment, allValidFilesReady, assertShipJsonSyntax, calculateMD5, classifyToken, createAccountResource, createDeploymentResource, createDomainResource, createTokenResource, Ship as default, deserializeLabels, extractSubdomain, filterJunk, formatFileSize, generateDeploymentUrl, generateDomainUrl, getENV, getValidFiles, hasUnbuiltMarker, hasUnsafeChars, isBlockedExtension, isCustomDomain, isDeployment, isPlatformDomain, isShipError, optimizeDeployPaths, pluralize, processFilesForBrowser, serializeLabels, validateApiKey, validateApiUrl, validateCaller, validateDeployFile, validateDeployPath, validateDeployToken, validateFileName, validateFiles, validateIdempotencyKey, validatePassword, validateToken };
|