@shipstatic/types 2.26.0-beta.2 → 2.26.0-beta.4

package/dist/index.d.ts

@@ -479,13 +479,25 @@ 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.
+     */
     available: boolean | null;
-    /** Why the name is unusable, null when valid — displayed verbatim. */
+    /**
+     * Why the name is unusable, displayed verbatim; null exactly when it IS
+     * usable. A name is unusable when it is invalid OR unavailable, and both
+     * carry a reason, so a client reads this field alone for the verdict and
+     * invents no copy of its own.
+     */
     reason: string | null;
 }
 /**
@@ -1825,6 +1837,15 @@ export declare function formatDuration(seconds: number): string;
  * why that case is `null` rather than a sentence.
  */
 export declare function formatTimeRemaining(expires: number, now?: number): string | null;
+/**
+ * A byte count as a person reads it: `"180 KB"`, `"2.5 MB"`, `"0 Bytes"`.
+ *
+ * Binary units, one decimal by default, and `decimals` for a surface with its
+ * own density (a dense table reads `"3 MB"` at 0). A deployment's size reads
+ * this way on every surface that states one: the console, the CLI, the deploy
+ * card and the API's own refusals, so one deployment is one number everywhere.
+ */
+export declare function formatFileSize(bytes: number, decimals?: number): string;
 /**
  * Universal deploy input — the union of every shape the SDK accepts.
  *

package/dist/index.js

@@ -1776,6 +1776,25 @@ function countOf(count, unit) {
     return `${count} ${unit}${count === 1 ? '' : 's'}`;
 }
 // =============================================================================
+// FILE SIZE
+// =============================================================================
+/**
+ * A byte count as a person reads it: `"180 KB"`, `"2.5 MB"`, `"0 Bytes"`.
+ *
+ * Binary units, one decimal by default, and `decimals` for a surface with its
+ * own density (a dense table reads `"3 MB"` at 0). A deployment's size reads
+ * this way on every surface that states one: the console, the CLI, the deploy
+ * card and the API's own refusals, so one deployment is one number everywhere.
+ */
+export function formatFileSize(bytes, decimals = 1) {
+    if (bytes === 0)
+        return '0 Bytes';
+    const k = 1024;
+    const sizes = ['Bytes', 'KB', 'MB', 'GB'];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return `${Number.parseFloat((bytes / k ** i).toFixed(decimals))} ${sizes[i]}`;
+}
+// =============================================================================
 // 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.2",
+  "version": "2.26.0-beta.4",
   "description": "Shared TypeScript types for the ShipStatic platform.",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts

@@ -538,13 +538,25 @@ 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.
+   */
   available: boolean | null;
-  /** Why the name is unusable, null when valid — displayed verbatim. */
+  /**
+   * Why the name is unusable, displayed verbatim; null exactly when it IS
+   * usable. A name is unusable when it is invalid OR unavailable, and both
+   * carry a reason, so a client reads this field alone for the verdict and
+   * invents no copy of its own.
+   */
   reason: string | null;
 }
 
@@ -2701,6 +2713,26 @@ function countOf(count: number, unit: string): string {
   return `${count} ${unit}${count === 1 ? '' : 's'}`;
 }
 
+// =============================================================================
+// FILE SIZE
+// =============================================================================
+
+/**
+ * A byte count as a person reads it: `"180 KB"`, `"2.5 MB"`, `"0 Bytes"`.
+ *
+ * Binary units, one decimal by default, and `decimals` for a surface with its
+ * own density (a dense table reads `"3 MB"` at 0). A deployment's size reads
+ * this way on every surface that states one: the console, the CLI, the deploy
+ * card and the API's own refusals, so one deployment is one number everywhere.
+ */
+export function formatFileSize(bytes: number, decimals: number = 1): string {
+  if (bytes === 0) return '0 Bytes';
+  const k = 1024;
+  const sizes = ['Bytes', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return `${Number.parseFloat((bytes / k ** i).toFixed(decimals))} ${sizes[i]}`;
+}
+
 // =============================================================================
 // 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.'),
 });
 
 // =============================================================================