@shipstatic/types 2.26.0-beta.1 → 2.26.0-beta.3

package/dist/index.d.ts

@@ -479,13 +479,28 @@ export interface SetupInstructionsResponse {
  * one key cannot mean both. See {@link DeploymentDeleteResponse} for the law.
  */
 export interface DomainValidateResponse {
-    /** Whether the domain is valid */
+    /** Whether the domain's SHAPE is usable: format, and the caller's own rules. */
     valid: boolean;
     /** Normalized domain name, null when invalid */
     normalized: string | null;
-    /** Whether the domain is available, null when invalid */
+    /**
+     * Whether nobody has registered the name yet; null when invalid.
+     *
+     * It answers "would creating this be new", not "would a write succeed": `PUT
+     * /domains/:domain` is an upsert, which is how a domain is re-pointed, so a
+     * caller's OWN domain is unavailable here and writable there. Availability
+     * does not depend on the kind of name; a custom domain answered `true`
+     * whoever owned it until 2026-09-17.
+     */
     available: boolean | null;
-    /** Why the name is unusable, null when valid — displayed verbatim. */
+    /**
+     * Why the name is unusable, null when it IS usable — displayed verbatim.
+     *
+     * A name is unusable when it is invalid OR unavailable, and both carry a
+     * reason. This said "null when valid" until 2026-09-17, which was already
+     * untrue of the endpoint it described: a registered name is valid, is
+     * unusable, and had no reason at all, which is why every client invented one.
+     */
     reason: string | null;
 }
 /**
@@ -1793,6 +1808,38 @@ export declare const MY_API_KEY_URL = "https://my.shipstatic.com/api-key";
  * it is.
  */
 export declare const PUBLIC_DEPLOYMENT_TTL_SECONDS: number;
+/**
+ * A span of time in words: `"3 days"`, `"5 hours"`, `"45 minutes"`.
+ *
+ * Minutes under two hours, hours under two days, and days beyond, each rounded
+ * to the nearest. The unit changes exactly where the larger one rounds to two,
+ * so the number never jumps as time passes (119 minutes, then 2 hours), and
+ * the two vaguest things a rounded clock can say, "1 hour" and "1 day", are
+ * never said. Rounding rather than truncating is what lets a deployment made a
+ * second ago read the lifetime it was given: "3 days", not "2 days". Days are
+ * the largest unit because nobody counts a deadline in weeks, and a month has
+ * no fixed length.
+ *
+ * A span that rounds to no minutes at all, zero and negative included, reads
+ * "less than a minute".
+ */
+export declare function formatDuration(seconds: number): string;
+/**
+ * The time left before a deadline, in words (`"3 days"`), or `null` once it
+ * has passed.
+ *
+ * `expires` is unix SECONDS, the wire's own field, taken as it arrives so that
+ * no caller converts it: the deploy card once read it as a date string and
+ * showed the same three days on every deployment for months. `now` is seconds
+ * too, and defaults to the clock.
+ *
+ * A surface that tells a person how long a deployment has left says it with
+ * this, so one deployment reads the same everywhere, whenever it is looked at.
+ * What a surface says around the words is its own ("Expires in", "It stays
+ * live for"), and so is what it says once the deadline has passed, which is
+ * why that case is `null` rather than a sentence.
+ */
+export declare function formatTimeRemaining(expires: number, now?: number): string | null;
 /**
  * Universal deploy input — the union of every shape the SDK accepts.
  *

package/dist/index.js

@@ -1725,6 +1725,57 @@ export const MY_API_KEY_URL = 'https://my.shipstatic.com/api-key';
  */
 export const PUBLIC_DEPLOYMENT_TTL_SECONDS = 3 * 24 * 60 * 60;
 // =============================================================================
+// TIME REMAINING
+// =============================================================================
+/**
+ * A span of time in words: `"3 days"`, `"5 hours"`, `"45 minutes"`.
+ *
+ * Minutes under two hours, hours under two days, and days beyond, each rounded
+ * to the nearest. The unit changes exactly where the larger one rounds to two,
+ * so the number never jumps as time passes (119 minutes, then 2 hours), and
+ * the two vaguest things a rounded clock can say, "1 hour" and "1 day", are
+ * never said. Rounding rather than truncating is what lets a deployment made a
+ * second ago read the lifetime it was given: "3 days", not "2 days". Days are
+ * the largest unit because nobody counts a deadline in weeks, and a month has
+ * no fixed length.
+ *
+ * A span that rounds to no minutes at all, zero and negative included, reads
+ * "less than a minute".
+ */
+export function formatDuration(seconds) {
+    const minutes = Math.round(seconds / 60);
+    if (!(minutes >= 1))
+        return 'less than a minute';
+    if (minutes < 120)
+        return countOf(minutes, 'minute');
+    const hours = Math.round(seconds / 3_600);
+    if (hours < 48)
+        return countOf(hours, 'hour');
+    return countOf(Math.round(seconds / 86_400), 'day');
+}
+/**
+ * The time left before a deadline, in words (`"3 days"`), or `null` once it
+ * has passed.
+ *
+ * `expires` is unix SECONDS, the wire's own field, taken as it arrives so that
+ * no caller converts it: the deploy card once read it as a date string and
+ * showed the same three days on every deployment for months. `now` is seconds
+ * too, and defaults to the clock.
+ *
+ * A surface that tells a person how long a deployment has left says it with
+ * this, so one deployment reads the same everywhere, whenever it is looked at.
+ * What a surface says around the words is its own ("Expires in", "It stays
+ * live for"), and so is what it says once the deadline has passed, which is
+ * why that case is `null` rather than a sentence.
+ */
+export function formatTimeRemaining(expires, now = Date.now() / 1_000) {
+    const seconds = expires - now;
+    return seconds > 0 ? formatDuration(seconds) : null;
+}
+function countOf(count, unit) {
+    return `${count} ${unit}${count === 1 ? '' : 's'}`;
+}
+// =============================================================================
 // FILE UPLOAD TYPES
 // =============================================================================
 /**

package/dist/schemas.js

@@ -165,10 +165,16 @@ export const DomainShareResponseSchema = z.object({
         .describe('The shareable DNS setup URL; whoever opens it sees the records to configure, with no API key.'),
 });
 export const DomainValidateResponseSchema = z.object({
-    valid: z.boolean().describe('Whether the domain name is valid.'),
+    valid: z.boolean().describe("Whether the domain's shape is usable."),
     normalized: z.string().nullable().describe('The normalized domain name; null when invalid.'),
-    available: z.boolean().nullable().describe('Whether the domain is available; null when invalid.'),
-    reason: z.string().nullable().describe('Why the name is unusable, for display; null when valid.'),
+    available: z
+        .boolean()
+        .nullable()
+        .describe('Whether nobody has registered the name yet; null when invalid. Creating it would be new; re-pointing your own domain is a write, not a create.'),
+    reason: z
+        .string()
+        .nullable()
+        .describe('Why the name is unusable, for display; null when it is usable.'),
 });
 // =============================================================================
 // ACCOUNT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipstatic/types",
-  "version": "2.26.0-beta.1",
+  "version": "2.26.0-beta.3",
   "description": "Shared TypeScript types for the ShipStatic platform.",
   "type": "module",
   "main": "./dist/index.js",
@@ -13,19 +13,12 @@
     "./schemas": {
       "types": "./dist/schemas.d.ts",
       "default": "./dist/schemas.js"
-    },
-    "./time": {
-      "types": "./dist/time.d.ts",
-      "default": "./dist/time.js"
     }
   },
   "typesVersions": {
     "*": {
       "schemas": [
         "./dist/schemas.d.ts"
-      ],
-      "time": [
-        "./dist/time.d.ts"
       ]
     }
   },

package/src/index.ts

@@ -538,13 +538,28 @@ export interface SetupInstructionsResponse {
  * one key cannot mean both. See {@link DeploymentDeleteResponse} for the law.
  */
 export interface DomainValidateResponse {
-  /** Whether the domain is valid */
+  /** Whether the domain's SHAPE is usable: format, and the caller's own rules. */
   valid: boolean;
   /** Normalized domain name, null when invalid */
   normalized: string | null;
-  /** Whether the domain is available, null when invalid */
+  /**
+   * Whether nobody has registered the name yet; null when invalid.
+   *
+   * It answers "would creating this be new", not "would a write succeed": `PUT
+   * /domains/:domain` is an upsert, which is how a domain is re-pointed, so a
+   * caller's OWN domain is unavailable here and writable there. Availability
+   * does not depend on the kind of name; a custom domain answered `true`
+   * whoever owned it until 2026-09-17.
+   */
   available: boolean | null;
-  /** Why the name is unusable, null when valid — displayed verbatim. */
+  /**
+   * Why the name is unusable, null when it IS usable — displayed verbatim.
+   *
+   * A name is unusable when it is invalid OR unavailable, and both carry a
+   * reason. This said "null when valid" until 2026-09-17, which was already
+   * untrue of the endpoint it described: a registered name is valid, is
+   * unusable, and had no reason at all, which is why every client invented one.
+   */
   reason: string | null;
 }
 
@@ -2646,6 +2661,61 @@ export const MY_API_KEY_URL = 'https://my.shipstatic.com/api-key';
  */
 export const PUBLIC_DEPLOYMENT_TTL_SECONDS = 3 * 24 * 60 * 60;
 
+// =============================================================================
+// TIME REMAINING
+// =============================================================================
+
+/**
+ * A span of time in words: `"3 days"`, `"5 hours"`, `"45 minutes"`.
+ *
+ * Minutes under two hours, hours under two days, and days beyond, each rounded
+ * to the nearest. The unit changes exactly where the larger one rounds to two,
+ * so the number never jumps as time passes (119 minutes, then 2 hours), and
+ * the two vaguest things a rounded clock can say, "1 hour" and "1 day", are
+ * never said. Rounding rather than truncating is what lets a deployment made a
+ * second ago read the lifetime it was given: "3 days", not "2 days". Days are
+ * the largest unit because nobody counts a deadline in weeks, and a month has
+ * no fixed length.
+ *
+ * A span that rounds to no minutes at all, zero and negative included, reads
+ * "less than a minute".
+ */
+export function formatDuration(seconds: number): string {
+  const minutes = Math.round(seconds / 60);
+  if (!(minutes >= 1)) return 'less than a minute';
+  if (minutes < 120) return countOf(minutes, 'minute');
+  const hours = Math.round(seconds / 3_600);
+  if (hours < 48) return countOf(hours, 'hour');
+  return countOf(Math.round(seconds / 86_400), 'day');
+}
+
+/**
+ * The time left before a deadline, in words (`"3 days"`), or `null` once it
+ * has passed.
+ *
+ * `expires` is unix SECONDS, the wire's own field, taken as it arrives so that
+ * no caller converts it: the deploy card once read it as a date string and
+ * showed the same three days on every deployment for months. `now` is seconds
+ * too, and defaults to the clock.
+ *
+ * A surface that tells a person how long a deployment has left says it with
+ * this, so one deployment reads the same everywhere, whenever it is looked at.
+ * What a surface says around the words is its own ("Expires in", "It stays
+ * live for"), and so is what it says once the deadline has passed, which is
+ * why that case is `null` rather than a sentence.
+ */
+export function formatTimeRemaining(
+  expires: number,
+  now: number = Date.now() / 1_000,
+): string | null {
+  const seconds = expires - now;
+  return seconds > 0 ? formatDuration(seconds) : null;
+}
+
+function countOf(count: number, unit: string): string {
+  return `${count} ${unit}${count === 1 ? '' : 's'}`;
+}
+
 // =============================================================================
 // RESOURCE INTERFACE CONTRACTS
 // =============================================================================

package/src/schemas.ts

@@ -218,10 +218,18 @@ export const DomainShareResponseSchema = z.object({
 });
 
 export const DomainValidateResponseSchema = z.object({
-  valid: z.boolean().describe('Whether the domain name is valid.'),
+  valid: z.boolean().describe("Whether the domain's shape is usable."),
   normalized: z.string().nullable().describe('The normalized domain name; null when invalid.'),
-  available: z.boolean().nullable().describe('Whether the domain is available; null when invalid.'),
-  reason: z.string().nullable().describe('Why the name is unusable, for display; null when valid.'),
+  available: z
+    .boolean()
+    .nullable()
+    .describe(
+      'Whether nobody has registered the name yet; null when invalid. Creating it would be new; re-pointing your own domain is a write, not a create.',
+    ),
+  reason: z
+    .string()
+    .nullable()
+    .describe('Why the name is unusable, for display; null when it is usable.'),
 });
 
 // =============================================================================

package/dist/time.d.ts

@@ -1,50 +0,0 @@
-/**
- * How long a deployment has left, in the words a person reads.
- *
- * When this module was written (2026-09-17) one deadline was told four ways:
- * the deploy card counted from now, the CLI and the marketing site from the
- * deployment's creation, the VS Code palette quoted the anonymous tier's fixed
- * lifetime, and the dashboard truncated, so a deployment made a second ago
- * read "2d" there and "3 days" everywhere else. The rule since: a surface that
- * tells a person how long a deployment has left says it with
- * `formatTimeRemaining`, and a duration a person reads about deployments is
- * spelled by `formatDuration`.
- *
- * The WORDS are the surface's own. A card says "Expires in", the marketing
- * site says "It stays live for", and each says something different once the
- * deadline has passed, which is why that case is `null` rather than a
- * sentence. What is owned here is the part that drifted silently: the unit,
- * the rounding, and what the clock is measured from.
- *
- * A subpath export (`@shipstatic/types/time`), for the same reason as
- * `/schemas`: a browser bundle importing only this carries only this. From the
- * main entry it would carry about a kilobyte of unrelated constants that a
- * bundler cannot prove are unused (1 KB gzipped, measured with the deploy
- * card's esbuild on 2026-09-17).
- */
-/**
- * A span of time in words: `"3 days"`, `"5 hours"`, `"45 minutes"`.
- *
- * Minutes under two hours, hours under two days, and days beyond, each rounded
- * to the nearest. The unit changes exactly where the larger one rounds to two,
- * so the number never jumps as time passes (119 minutes, then 2 hours), and
- * the two vaguest things a rounded clock can say, "1 hour" and "1 day", are
- * never said. Rounding rather than truncating is what lets a deployment made a
- * second ago read the lifetime it was given: "3 days", not "2 days". Days are
- * the largest unit because nobody counts a deadline in weeks, and a month has
- * no fixed length.
- *
- * A span that rounds to no minutes at all, zero and negative included, reads
- * "less than a minute".
- */
-export declare function formatDuration(seconds: number): string;
-/**
- * The time left before a deadline, in words (`"3 days"`), or `null` once it
- * has passed.
- *
- * `expires` is unix SECONDS, the wire's own field, taken as it arrives so that
- * no caller converts it: the deploy card once read it as a date string and
- * showed the same three days on every deployment for months. `now` is seconds
- * too, and defaults to the clock.
- */
-export declare function formatTimeRemaining(expires: number, now?: number): string | null;

package/dist/time.js

@@ -1,66 +0,0 @@
-/**
- * How long a deployment has left, in the words a person reads.
- *
- * When this module was written (2026-09-17) one deadline was told four ways:
- * the deploy card counted from now, the CLI and the marketing site from the
- * deployment's creation, the VS Code palette quoted the anonymous tier's fixed
- * lifetime, and the dashboard truncated, so a deployment made a second ago
- * read "2d" there and "3 days" everywhere else. The rule since: a surface that
- * tells a person how long a deployment has left says it with
- * `formatTimeRemaining`, and a duration a person reads about deployments is
- * spelled by `formatDuration`.
- *
- * The WORDS are the surface's own. A card says "Expires in", the marketing
- * site says "It stays live for", and each says something different once the
- * deadline has passed, which is why that case is `null` rather than a
- * sentence. What is owned here is the part that drifted silently: the unit,
- * the rounding, and what the clock is measured from.
- *
- * A subpath export (`@shipstatic/types/time`), for the same reason as
- * `/schemas`: a browser bundle importing only this carries only this. From the
- * main entry it would carry about a kilobyte of unrelated constants that a
- * bundler cannot prove are unused (1 KB gzipped, measured with the deploy
- * card's esbuild on 2026-09-17).
- */
-/**
- * A span of time in words: `"3 days"`, `"5 hours"`, `"45 minutes"`.
- *
- * Minutes under two hours, hours under two days, and days beyond, each rounded
- * to the nearest. The unit changes exactly where the larger one rounds to two,
- * so the number never jumps as time passes (119 minutes, then 2 hours), and
- * the two vaguest things a rounded clock can say, "1 hour" and "1 day", are
- * never said. Rounding rather than truncating is what lets a deployment made a
- * second ago read the lifetime it was given: "3 days", not "2 days". Days are
- * the largest unit because nobody counts a deadline in weeks, and a month has
- * no fixed length.
- *
- * A span that rounds to no minutes at all, zero and negative included, reads
- * "less than a minute".
- */
-export function formatDuration(seconds) {
-    const minutes = Math.round(seconds / 60);
-    if (!(minutes >= 1))
-        return 'less than a minute';
-    if (minutes < 120)
-        return countOf(minutes, 'minute');
-    const hours = Math.round(seconds / 3_600);
-    if (hours < 48)
-        return countOf(hours, 'hour');
-    return countOf(Math.round(seconds / 86_400), 'day');
-}
-/**
- * The time left before a deadline, in words (`"3 days"`), or `null` once it
- * has passed.
- *
- * `expires` is unix SECONDS, the wire's own field, taken as it arrives so that
- * no caller converts it: the deploy card once read it as a date string and
- * showed the same three days on every deployment for months. `now` is seconds
- * too, and defaults to the clock.
- */
-export function formatTimeRemaining(expires, now = Date.now() / 1_000) {
-    const seconds = expires - now;
-    return seconds > 0 ? formatDuration(seconds) : null;
-}
-function countOf(count, unit) {
-    return `${count} ${unit}${count === 1 ? '' : 's'}`;
-}

package/src/time.ts

@@ -1,69 +0,0 @@
-/**
- * How long a deployment has left, in the words a person reads.
- *
- * When this module was written (2026-09-17) one deadline was told four ways:
- * the deploy card counted from now, the CLI and the marketing site from the
- * deployment's creation, the VS Code palette quoted the anonymous tier's fixed
- * lifetime, and the dashboard truncated, so a deployment made a second ago
- * read "2d" there and "3 days" everywhere else. The rule since: a surface that
- * tells a person how long a deployment has left says it with
- * `formatTimeRemaining`, and a duration a person reads about deployments is
- * spelled by `formatDuration`.
- *
- * The WORDS are the surface's own. A card says "Expires in", the marketing
- * site says "It stays live for", and each says something different once the
- * deadline has passed, which is why that case is `null` rather than a
- * sentence. What is owned here is the part that drifted silently: the unit,
- * the rounding, and what the clock is measured from.
- *
- * A subpath export (`@shipstatic/types/time`), for the same reason as
- * `/schemas`: a browser bundle importing only this carries only this. From the
- * main entry it would carry about a kilobyte of unrelated constants that a
- * bundler cannot prove are unused (1 KB gzipped, measured with the deploy
- * card's esbuild on 2026-09-17).
- */
-
-/**
- * A span of time in words: `"3 days"`, `"5 hours"`, `"45 minutes"`.
- *
- * Minutes under two hours, hours under two days, and days beyond, each rounded
- * to the nearest. The unit changes exactly where the larger one rounds to two,
- * so the number never jumps as time passes (119 minutes, then 2 hours), and
- * the two vaguest things a rounded clock can say, "1 hour" and "1 day", are
- * never said. Rounding rather than truncating is what lets a deployment made a
- * second ago read the lifetime it was given: "3 days", not "2 days". Days are
- * the largest unit because nobody counts a deadline in weeks, and a month has
- * no fixed length.
- *
- * A span that rounds to no minutes at all, zero and negative included, reads
- * "less than a minute".
- */
-export function formatDuration(seconds: number): string {
-  const minutes = Math.round(seconds / 60);
-  if (!(minutes >= 1)) return 'less than a minute';
-  if (minutes < 120) return countOf(minutes, 'minute');
-  const hours = Math.round(seconds / 3_600);
-  if (hours < 48) return countOf(hours, 'hour');
-  return countOf(Math.round(seconds / 86_400), 'day');
-}
-
-/**
- * The time left before a deadline, in words (`"3 days"`), or `null` once it
- * has passed.
- *
- * `expires` is unix SECONDS, the wire's own field, taken as it arrives so that
- * no caller converts it: the deploy card once read it as a date string and
- * showed the same three days on every deployment for months. `now` is seconds
- * too, and defaults to the clock.
- */
-export function formatTimeRemaining(
-  expires: number,
-  now: number = Date.now() / 1_000,
-): string | null {
-  const seconds = expires - now;
-  return seconds > 0 ? formatDuration(seconds) : null;
-}
-
-function countOf(count: number, unit: string): string {
-  return `${count} ${unit}${count === 1 ? '' : 's'}`;
-}