@shipstatic/types 2.26.0-beta.2 → 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;
 }
 /**

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.2",
+  "version": "2.26.0-beta.3",
   "description": "Shared TypeScript types for the ShipStatic platform.",
   "type": "module",
   "main": "./dist/index.js",

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;
 }
 

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.'),
 });
 
 // =============================================================================