@shipstatic/types 0.8.10 → 0.9.0

package/README.md

@@ -21,7 +21,7 @@ npm install @shipstatic/types
 ```typescript
 import type {
   Deployment, DeploymentListResponse,
-  Domain, DomainListResponse, DnsRecord, DomainDnsResponse, DomainRecordsResponse, DomainValidateResponse,
+  Domain, DomainSetResult, DomainListResponse, DnsRecord, DomainDnsResponse, DomainRecordsResponse, DomainValidateResponse,
   Token, TokenListItem, TokenListResponse, TokenCreateResponse,
   Account, AccountUsage, AccountOverrides,
   StaticFile

package/dist/index.d.ts

@@ -94,6 +94,20 @@ export interface Domain {
     /** Total deployment links */
     links: number;
 }
+/**
+ * Return shape of `domains.set()` — `Domain` plus an SDK-derived flag indicating
+ * whether the underlying `PUT /domains/:name` created the record (HTTP 201) or
+ * updated an existing one (HTTP 200).
+ *
+ * `isCreate` is not part of the wire format — the API returns a plain `Domain`
+ * body. The SDK derives the flag from the HTTP status code so callers (notably
+ * the CLI) can format different output for the create vs repoint paths without
+ * a second round-trip.
+ */
+export interface DomainSetResult extends Domain {
+    /** `true` when this call created a new domain; `false` when it updated an existing one. */
+    isCreate: boolean;
+}
 /**
  * Response for listing domains
  */
@@ -536,23 +550,21 @@ export interface StaticFile {
     size: number;
 }
 /**
- * Standard platform configuration format used by all clients
- */
-export interface PlatformConfig {
-    apiUrl?: string;
-    deployToken?: string;
-    apiKey?: string;
-}
-/**
- * Resolved configuration with required apiUrl.
- * This is the normalized config after merging options, env, and config files.
+ * Resolved client configuration with `apiUrl` defaulted.
+ *
+ * Produced by the SDK after layering its credential sources (constructor
+ * options on top of `SHIP_*` env vars in Node; constructor options only in
+ * Browser) and applying the `DEFAULT_API` fallback. File-based sources
+ * (`.shiprc`, `package.json` `"ship"` key) are the CLI's responsibility and
+ * are merged in *before* construction — by the time a `ResolvedConfig`
+ * exists, every source has already collapsed into the constructor argument.
  */
 export interface ResolvedConfig {
-    /** API URL (always present after resolution, defaults to DEFAULT_API) */
+    /** API URL — always present after resolution, defaults to `DEFAULT_API`. */
     apiUrl: string;
-    /** API key for authenticated deployments */
+    /** API key for authenticated deployments. */
     apiKey?: string;
-    /** Deploy token for single-use deployments */
+    /** Deploy token for single-use deployments. */
     deployToken?: string;
 }
 /**
@@ -572,12 +584,26 @@ export interface ProgressInfo {
 /** Default API URL if not otherwise configured. */
 export declare const DEFAULT_API = "https://api.shipstatic.com";
 /**
- * Deploy input type - environment-specific
+ * Browser-specific deploy input — an array of `File` objects (typically from
+ * `<input type="file">` or drag-and-drop). The Browser SDK rejects any other
+ * shape at runtime.
+ */
+export type BrowserDeployInput = File[];
+/**
+ * Node-specific deploy input — file or directory path(s) on disk. A single
+ * path or an array of paths; directories are walked recursively. The Node
+ * SDK rejects any other shape at runtime.
+ */
+export type NodeDeployInput = string | string[];
+/**
+ * Universal deploy input — the union of every platform's accepted shape.
  *
- * Browser: File[] - array of File objects
- * Node.js: string | string[] - file/directory paths
+ * Prefer the platform-specific aliases (`BrowserDeployInput` /
+ * `NodeDeployInput`) when writing platform-specific code; `DeployInput` is
+ * the right type only for code that genuinely needs to accept either. Each
+ * platform's SDK validates at runtime and throws on the wrong shape.
  */
-export type DeployInput = File[] | string | string[];
+export type DeployInput = BrowserDeployInput | NodeDeployInput;
 /**
  * Options for deployment creation at the API contract level.
  * SDK implementations may extend with additional options (timeout, signal, callbacks, etc.).
@@ -623,7 +649,7 @@ export interface DomainResource {
     set: (name: string, options?: {
         deployment?: string;
         labels?: string[];
-    }) => Promise<Domain>;
+    }) => Promise<DomainSetResult>;
     list: () => Promise<DomainListResponse>;
     get: (name: string) => Promise<Domain>;
     remove: (name: string) => Promise<void>;

package/package.json

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

package/src/index.ts

@@ -112,6 +112,21 @@ export interface Domain {
   links: number;
 }
 
+/**
+ * Return shape of `domains.set()` — `Domain` plus an SDK-derived flag indicating
+ * whether the underlying `PUT /domains/:name` created the record (HTTP 201) or
+ * updated an existing one (HTTP 200).
+ *
+ * `isCreate` is not part of the wire format — the API returns a plain `Domain`
+ * body. The SDK derives the flag from the HTTP status code so callers (notably
+ * the CLI) can format different output for the create vs repoint paths without
+ * a second round-trip.
+ */
+export interface DomainSetResult extends Domain {
+  /** `true` when this call created a new domain; `false` when it updated an existing one. */
+  isCreate: boolean;
+}
+
 /**
  * Response for listing domains
  */
@@ -822,24 +837,21 @@ export interface StaticFile {
 // =============================================================================
 
 /**
- * Standard platform configuration format used by all clients
- */
-export interface PlatformConfig {
-  apiUrl?: string;
-  deployToken?: string;
-  apiKey?: string;
-}
-
-/**
- * Resolved configuration with required apiUrl.
- * This is the normalized config after merging options, env, and config files.
+ * Resolved client configuration with `apiUrl` defaulted.
+ *
+ * Produced by the SDK after layering its credential sources (constructor
+ * options on top of `SHIP_*` env vars in Node; constructor options only in
+ * Browser) and applying the `DEFAULT_API` fallback. File-based sources
+ * (`.shiprc`, `package.json` `"ship"` key) are the CLI's responsibility and
+ * are merged in *before* construction — by the time a `ResolvedConfig`
+ * exists, every source has already collapsed into the constructor argument.
  */
 export interface ResolvedConfig {
-  /** API URL (always present after resolution, defaults to DEFAULT_API) */
+  /** API URL — always present after resolution, defaults to `DEFAULT_API`. */
   apiUrl: string;
-  /** API key for authenticated deployments */
+  /** API key for authenticated deployments. */
   apiKey?: string;
-  /** Deploy token for single-use deployments */
+  /** Deploy token for single-use deployments. */
   deployToken?: string;
 }
 
@@ -874,12 +886,28 @@ export const DEFAULT_API = 'https://api.shipstatic.com';
 // =============================================================================
 
 /**
- * Deploy input type - environment-specific
+ * Browser-specific deploy input — an array of `File` objects (typically from
+ * `<input type="file">` or drag-and-drop). The Browser SDK rejects any other
+ * shape at runtime.
+ */
+export type BrowserDeployInput = File[];
+
+/**
+ * Node-specific deploy input — file or directory path(s) on disk. A single
+ * path or an array of paths; directories are walked recursively. The Node
+ * SDK rejects any other shape at runtime.
+ */
+export type NodeDeployInput = string | string[];
+
+/**
+ * Universal deploy input — the union of every platform's accepted shape.
  *
- * Browser: File[] - array of File objects
- * Node.js: string | string[] - file/directory paths
+ * Prefer the platform-specific aliases (`BrowserDeployInput` /
+ * `NodeDeployInput`) when writing platform-specific code; `DeployInput` is
+ * the right type only for code that genuinely needs to accept either. Each
+ * platform's SDK validates at runtime and throws on the wrong shape.
  */
-export type DeployInput = File[] | string | string[];
+export type DeployInput = BrowserDeployInput | NodeDeployInput;
 
 /**
  * Options for deployment creation at the API contract level.
@@ -923,7 +951,7 @@ export interface DeploymentResource {
  * Domain resource interface - the contract all implementations must follow
  */
 export interface DomainResource {
-  set: (name: string, options?: { deployment?: string; labels?: string[] }) => Promise<Domain>;
+  set: (name: string, options?: { deployment?: string; labels?: string[] }) => Promise<DomainSetResult>;
   list: () => Promise<DomainListResponse>;
   get: (name: string) => Promise<Domain>;
   remove: (name: string) => Promise<void>;