@shipstatic/types 0.9.7 → 0.9.9

package/README.md

@@ -68,7 +68,7 @@ try { response = await fetch(url); }
 catch (cause) { throw ShipError.fromFetchError(cause, 'Get account'); }
 ```
 
-`fromHttpResponse` trusts the body's `error` field when it's a known server-producible `ErrorType` — so a server's `ShipError.validation(...)` round-trips back to `ErrorType.Validation` on the client. For non-API responses (CDN errors, intermediaries) or malformed bodies it falls back to status-derived (401 → `Authentication`, 429 → `RateLimit`, else → `Api`). Body's `message` and `details` are preserved best-effort.
+`fromHttpResponse` trusts the body's `error` field when it's a known server-producible `ErrorType` — so a server's `ShipError.validation(...)` round-trips back to `ErrorType.Validation` on the client. For non-API responses (CDN errors, intermediaries) or malformed bodies it falls back to status-derived (401 → `Authentication`, 403 → `Forbidden`, 429 → `RateLimit`, else → `Api`). Client-only types (`Network`, `Cancelled`, `File`, `Config`) are filtered out of the trusted set. Body's `message` and `details` are preserved best-effort.
 
 `fromFetchError` routes by the thrown cause: an existing `ShipError` is returned unchanged, `AbortError` becomes `Cancelled`, a fetch `TypeError` becomes `Network`, anything else becomes `Api` (with no HTTP status — the request never reached the server).
 
@@ -159,6 +159,15 @@ import {
 } from '@shipstatic/types';
 ```
 
+### Password Utilities
+
+```typescript
+import {
+  PASSWORD_CONSTRAINTS,   // { MIN_LENGTH: 6, MAX_LENGTH: 128 }
+  validatePassword,       // (value: unknown) => string | undefined
+} from '@shipstatic/types';
+```
+
 ### Constants
 
 ```typescript

package/dist/index.d.ts

@@ -397,7 +397,7 @@ export declare class ShipError extends Error {
     static validation(message: string, details?: unknown): ShipError;
     static notFound(resource: string, id?: string): ShipError;
     static forbidden(message: string, details?: unknown): ShipError;
-    static rateLimit(message?: string): ShipError;
+    static rateLimit(message?: string, details?: unknown): ShipError;
     /**
      * Construct an Authentication (401) error.
      *
@@ -412,12 +412,12 @@ export declare class ShipError extends Error {
      * `internal`. Other `details` keys round-trip normally.
      */
     static authentication(message?: string, details?: unknown): ShipError;
-    static business(message: string, status?: number): ShipError;
+    static business(message: string, status?: number, details?: unknown): ShipError;
     static network(message: string, details?: unknown): ShipError;
-    static cancelled(message: string): ShipError;
+    static cancelled(message: string, details?: unknown): ShipError;
     static file(message: string, details?: unknown): ShipError;
     static config(message: string, details?: unknown): ShipError;
-    static api(message: string, status?: number): ShipError;
+    static api(message: string, status?: number, details?: unknown): ShipError;
     isClientError(): boolean;
     isNetworkError(): boolean;
     isAuthError(): boolean;
@@ -1012,3 +1012,17 @@ export declare const PASSWORD_CONSTRAINTS: {
     /** Maximum password length in characters */
     readonly MAX_LENGTH: 128;
 };
+/**
+ * Validate an optional deployment password and return it normalized.
+ *
+ * Absent (`undefined` / `null`) → returns `undefined`; an unprotected
+ * deployment is a valid choice. Present → must be a string within
+ * `PASSWORD_CONSTRAINTS` length bounds. Whitespace is preserved verbatim —
+ * significant. Throws `ShipError.validation` on breach.
+ *
+ * Single source of truth shared by SDK (client-side validation, return
+ * ignored) and API (server-side enforcement, return threaded into config).
+ * Length is part of the wire-format contract; strength rules, if added later,
+ * stay server-side. See `CLAUDE.md` "Validation: format vs policy".
+ */
+export declare function validatePassword(value: unknown): string | undefined;

package/dist/index.js

@@ -247,8 +247,8 @@ export class ShipError extends Error {
     static forbidden(message, details) {
         return new ShipError(ErrorType.Forbidden, message, 403, details);
     }
-    static rateLimit(message = "Too many requests") {
-        return new ShipError(ErrorType.RateLimit, message, 429);
+    static rateLimit(message = "Too many requests", details) {
+        return new ShipError(ErrorType.RateLimit, message, 429, details);
     }
     /**
      * Construct an Authentication (401) error.
@@ -266,14 +266,14 @@ export class ShipError extends Error {
     static authentication(message = "Authentication required", details) {
         return new ShipError(ErrorType.Authentication, message, 401, details);
     }
-    static business(message, status = 400) {
-        return new ShipError(ErrorType.Business, message, status);
+    static business(message, status = 400, details) {
+        return new ShipError(ErrorType.Business, message, status, details);
     }
     static network(message, details) {
         return new ShipError(ErrorType.Network, message, undefined, details);
     }
-    static cancelled(message) {
-        return new ShipError(ErrorType.Cancelled, message);
+    static cancelled(message, details) {
+        return new ShipError(ErrorType.Cancelled, message, undefined, details);
     }
     static file(message, details) {
         return new ShipError(ErrorType.File, message, undefined, details);
@@ -281,8 +281,8 @@ export class ShipError extends Error {
     static config(message, details) {
         return new ShipError(ErrorType.Config, message, undefined, details);
     }
-    static api(message, status = 500) {
-        return new ShipError(ErrorType.Api, message, status);
+    static api(message, status = 500, details) {
+        return new ShipError(ErrorType.Api, message, status, details);
     }
     // Semantic-category type guards. For specific-type checks, use
     // `error.type === ErrorType.X` directly or the generic `isType(t)`.
@@ -661,3 +661,28 @@ export const PASSWORD_CONSTRAINTS = {
     /** Maximum password length in characters */
     MAX_LENGTH: 128,
 };
+/**
+ * Validate an optional deployment password and return it normalized.
+ *
+ * Absent (`undefined` / `null`) → returns `undefined`; an unprotected
+ * deployment is a valid choice. Present → must be a string within
+ * `PASSWORD_CONSTRAINTS` length bounds. Whitespace is preserved verbatim —
+ * significant. Throws `ShipError.validation` on breach.
+ *
+ * Single source of truth shared by SDK (client-side validation, return
+ * ignored) and API (server-side enforcement, return threaded into config).
+ * Length is part of the wire-format contract; strength rules, if added later,
+ * stay server-side. See `CLAUDE.md` "Validation: format vs policy".
+ */
+export function validatePassword(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'string') {
+        throw ShipError.validation('Password must be a string');
+    }
+    if (value.length < PASSWORD_CONSTRAINTS.MIN_LENGTH ||
+        value.length > PASSWORD_CONSTRAINTS.MAX_LENGTH) {
+        throw ShipError.validation(`Password must be between ${PASSWORD_CONSTRAINTS.MIN_LENGTH} and ${PASSWORD_CONSTRAINTS.MAX_LENGTH} characters`);
+    }
+    return value;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipstatic/types",
-  "version": "0.9.7",
+  "version": "0.9.9",
   "description": "Shared types for ShipStatic platform",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts

@@ -574,8 +574,8 @@ export class ShipError extends Error {
     return new ShipError(ErrorType.Forbidden, message, 403, details);
   }
 
-  static rateLimit(message: string = "Too many requests"): ShipError {
-    return new ShipError(ErrorType.RateLimit, message, 429);
+  static rateLimit(message: string = "Too many requests", details?: unknown): ShipError {
+    return new ShipError(ErrorType.RateLimit, message, 429, details);
   }
 
   /**
@@ -595,16 +595,16 @@ export class ShipError extends Error {
     return new ShipError(ErrorType.Authentication, message, 401, details);
   }
 
-  static business(message: string, status: number = 400): ShipError {
-    return new ShipError(ErrorType.Business, message, status);
+  static business(message: string, status: number = 400, details?: unknown): ShipError {
+    return new ShipError(ErrorType.Business, message, status, details);
   }
 
   static network(message: string, details?: unknown): ShipError {
     return new ShipError(ErrorType.Network, message, undefined, details);
   }
 
-  static cancelled(message: string): ShipError {
-    return new ShipError(ErrorType.Cancelled, message);
+  static cancelled(message: string, details?: unknown): ShipError {
+    return new ShipError(ErrorType.Cancelled, message, undefined, details);
   }
 
   static file(message: string, details?: unknown): ShipError {
@@ -615,8 +615,8 @@ export class ShipError extends Error {
     return new ShipError(ErrorType.Config, message, undefined, details);
   }
 
-  static api(message: string, status: number = 500): ShipError {
-    return new ShipError(ErrorType.Api, message, status);
+  static api(message: string, status: number = 500, details?: unknown): ShipError {
+    return new ShipError(ErrorType.Api, message, status, details);
   }
 
   // Semantic-category type guards. For specific-type checks, use
@@ -1524,4 +1524,33 @@ export const PASSWORD_CONSTRAINTS = {
   MIN_LENGTH: 6,
   /** Maximum password length in characters */
   MAX_LENGTH: 128,
-} as const;
+} as const;
+
+/**
+ * Validate an optional deployment password and return it normalized.
+ *
+ * Absent (`undefined` / `null`) → returns `undefined`; an unprotected
+ * deployment is a valid choice. Present → must be a string within
+ * `PASSWORD_CONSTRAINTS` length bounds. Whitespace is preserved verbatim —
+ * significant. Throws `ShipError.validation` on breach.
+ *
+ * Single source of truth shared by SDK (client-side validation, return
+ * ignored) and API (server-side enforcement, return threaded into config).
+ * Length is part of the wire-format contract; strength rules, if added later,
+ * stay server-side. See `CLAUDE.md` "Validation: format vs policy".
+ */
+export function validatePassword(value: unknown): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== 'string') {
+    throw ShipError.validation('Password must be a string');
+  }
+  if (
+    value.length < PASSWORD_CONSTRAINTS.MIN_LENGTH ||
+    value.length > PASSWORD_CONSTRAINTS.MAX_LENGTH
+  ) {
+    throw ShipError.validation(
+      `Password must be between ${PASSWORD_CONSTRAINTS.MIN_LENGTH} and ${PASSWORD_CONSTRAINTS.MAX_LENGTH} characters`,
+    );
+  }
+  return value;
+}