@shipstatic/types 2.5.0-beta.19 → 2.5.0-beta.20

package/dist/index.d.ts

@@ -12,6 +12,28 @@ export declare const DeploymentStatus: {
     readonly DELETING: "deleting";
 };
 export type DeploymentStatusType = (typeof DeploymentStatus)[keyof typeof DeploymentStatus];
+/**
+ * Which client made a deployment — the origin-tracking vocabulary.
+ *
+ * A closed set with many authors: the CLI, the SDK, the dashboard, both MCP
+ * transports, the GitHub Action, the n8n node and the VS Code extension each
+ * name themselves here. It lived in the API's config until 2026-08-06, where
+ * being server-side made it unenforceable in the one direction that matters —
+ * every client wrote a bare string, and a value outside the set was **silently
+ * dropped** by the server, so a typo did not fail anywhere. It stopped
+ * recording where deploys came from and said nothing.
+ */
+export declare const DeploymentVia: {
+    readonly WEB: "web";
+    readonly SDK: "sdk";
+    readonly CLI: "cli";
+    readonly MCP: "mcp";
+    readonly GIT: "git";
+    readonly N8N: "n8n";
+    readonly GPT: "gpt";
+    readonly VSC: "vsc";
+};
+export type DeploymentViaType = (typeof DeploymentVia)[keyof typeof DeploymentVia];
 /**
  * Core deployment object - used in both API responses and SDK
  */
@@ -32,7 +54,15 @@ export interface Deployment {
     readonly password: boolean;
     /** Labels for categorization and filtering (lowercase, alphanumeric with separators). Always present, empty array when none. */
     labels: string[];
-    /** The client/tool used to create this deployment (e.g., 'web', 'sdk', 'cli'), null if unknown */
+    /**
+     * The client/tool that created this deployment, null if unknown.
+     *
+     * Deliberately wider than {@link DeploymentViaType}: this is stored data,
+     * and rows predate the vocabulary being closed. Narrowing the ENTITY would
+     * be a claim about every row already in the database; narrowing the
+     * REQUEST option ({@link DeploymentUploadOptions.via}) is a claim about
+     * what a client may send, which is ours to make.
+     */
     readonly via: string | null;
     /** Unix timestamp (seconds) when deployment was created */
     readonly created: number;
@@ -324,10 +354,33 @@ export interface DomainRecordsResponse {
  * API would reject the same value the same way.
  */
 export declare const IDEMPOTENCY_KEY_CONSTRAINTS: {
+    /**
+     * HTTP header name. Here for the same reason {@link CALLER.HEADER} is: a
+     * wire header has two ends, and the package that owns the value's format
+     * is the only place both ends can read its name from.
+     */
+    readonly HEADER: "Idempotency-Key";
     readonly MAX_LENGTH: 256;
     /** How long a stored 201 stays replayable. */
     readonly WINDOW_SECONDS: number;
 };
+/**
+ * Normalize a `via` value from any transport — trimmed, lowercased, and a
+ * member of {@link DeploymentVia}, or `undefined`.
+ *
+ * A format rule by this package's own test: a client can decide offline
+ * whether a value is well-formed, and the API reaches the same verdict on the
+ * same input. It lived server-side until 2026-08-06, which meant clients could
+ * only learn their label was unusable by noticing analytics had gone quiet.
+ *
+ * **Not knowing your `via` is not an error** — an unrecognized value yields
+ * `undefined` rather than throwing, because origin tracking is telemetry and a
+ * deploy must never fail over it. A caller that has an honest default should
+ * prefer it (`normalizeVia(process.env.SHIP_VIA) ?? DeploymentVia.CLI`): the
+ * deploy really did come from the CLI, so recording that beats recording
+ * nothing.
+ */
+export declare function normalizeVia(value: unknown): DeploymentViaType | undefined;
 /**
  * Validate an idempotency key, returning the trimmed value or `undefined`
  * when none was supplied. Throws {@link ShipError.validation} when the value
@@ -1127,8 +1180,12 @@ export type DeployInput = File[] | string | string[];
 export interface DeploymentUploadOptions {
     /** Optional labels for categorization and filtering */
     labels?: string[];
-    /** Client identifier (e.g., 'cli', 'sdk', 'web') */
-    via?: string;
+    /**
+     * Which client is making this deploy. Closed, because the server silently
+     * ignores anything outside the set — so an unchecked string turned a typo
+     * into missing analytics rather than an error. See {@link DeploymentVia}.
+     */
+    via?: DeploymentViaType;
     /**
      * Optional password that protects this deployment.
      *

package/dist/index.js

@@ -14,6 +14,27 @@ export const DeploymentStatus = {
     FAILED: 'failed',
     DELETING: 'deleting',
 };
+/**
+ * Which client made a deployment — the origin-tracking vocabulary.
+ *
+ * A closed set with many authors: the CLI, the SDK, the dashboard, both MCP
+ * transports, the GitHub Action, the n8n node and the VS Code extension each
+ * name themselves here. It lived in the API's config until 2026-08-06, where
+ * being server-side made it unenforceable in the one direction that matters —
+ * every client wrote a bare string, and a value outside the set was **silently
+ * dropped** by the server, so a typo did not fail anywhere. It stopped
+ * recording where deploys came from and said nothing.
+ */
+export const DeploymentVia = {
+    WEB: 'web',
+    SDK: 'sdk',
+    CLI: 'cli',
+    MCP: 'mcp',
+    GIT: 'git',
+    N8N: 'n8n',
+    GPT: 'gpt',
+    VSC: 'vsc',
+};
 /**
  * Every path the public API answers on, declared once.
  *
@@ -95,10 +116,40 @@ export const DomainStatus = {
  * API would reject the same value the same way.
  */
 export const IDEMPOTENCY_KEY_CONSTRAINTS = {
+    /**
+     * HTTP header name. Here for the same reason {@link CALLER.HEADER} is: a
+     * wire header has two ends, and the package that owns the value's format
+     * is the only place both ends can read its name from.
+     */
+    HEADER: 'Idempotency-Key',
     MAX_LENGTH: 256,
     /** How long a stored 201 stays replayable. */
     WINDOW_SECONDS: 24 * 60 * 60,
 };
+/**
+ * Normalize a `via` value from any transport — trimmed, lowercased, and a
+ * member of {@link DeploymentVia}, or `undefined`.
+ *
+ * A format rule by this package's own test: a client can decide offline
+ * whether a value is well-formed, and the API reaches the same verdict on the
+ * same input. It lived server-side until 2026-08-06, which meant clients could
+ * only learn their label was unusable by noticing analytics had gone quiet.
+ *
+ * **Not knowing your `via` is not an error** — an unrecognized value yields
+ * `undefined` rather than throwing, because origin tracking is telemetry and a
+ * deploy must never fail over it. A caller that has an honest default should
+ * prefer it (`normalizeVia(process.env.SHIP_VIA) ?? DeploymentVia.CLI`): the
+ * deploy really did come from the CLI, so recording that beats recording
+ * nothing.
+ */
+export function normalizeVia(value) {
+    if (!value || typeof value !== 'string')
+        return undefined;
+    const via = value.trim().toLowerCase();
+    return Object.values(DeploymentVia).includes(via)
+        ? via
+        : undefined;
+}
 /**
  * Validate an idempotency key, returning the trimmed value or `undefined`
  * when none was supplied. Throws {@link ShipError.validation} when the value

package/package.json

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

package/src/index.ts

@@ -19,6 +19,30 @@ export const DeploymentStatus = {
 
 export type DeploymentStatusType = (typeof DeploymentStatus)[keyof typeof DeploymentStatus];
 
+/**
+ * Which client made a deployment — the origin-tracking vocabulary.
+ *
+ * A closed set with many authors: the CLI, the SDK, the dashboard, both MCP
+ * transports, the GitHub Action, the n8n node and the VS Code extension each
+ * name themselves here. It lived in the API's config until 2026-08-06, where
+ * being server-side made it unenforceable in the one direction that matters —
+ * every client wrote a bare string, and a value outside the set was **silently
+ * dropped** by the server, so a typo did not fail anywhere. It stopped
+ * recording where deploys came from and said nothing.
+ */
+export const DeploymentVia = {
+  WEB: 'web',
+  SDK: 'sdk',
+  CLI: 'cli',
+  MCP: 'mcp',
+  GIT: 'git',
+  N8N: 'n8n',
+  GPT: 'gpt',
+  VSC: 'vsc',
+} as const;
+
+export type DeploymentViaType = (typeof DeploymentVia)[keyof typeof DeploymentVia];
+
 /**
  * Core deployment object - used in both API responses and SDK
  */
@@ -39,7 +63,15 @@ export interface Deployment {
   readonly password: boolean;
   /** Labels for categorization and filtering (lowercase, alphanumeric with separators). Always present, empty array when none. */
   labels: string[];
-  /** The client/tool used to create this deployment (e.g., 'web', 'sdk', 'cli'), null if unknown */
+  /**
+   * The client/tool that created this deployment, null if unknown.
+   *
+   * Deliberately wider than {@link DeploymentViaType}: this is stored data,
+   * and rows predate the vocabulary being closed. Narrowing the ENTITY would
+   * be a claim about every row already in the database; narrowing the
+   * REQUEST option ({@link DeploymentUploadOptions.via}) is a claim about
+   * what a client may send, which is ours to make.
+   */
   readonly via: string | null;
   /** Unix timestamp (seconds) when deployment was created */
   readonly created: number;
@@ -355,11 +387,41 @@ export interface DomainRecordsResponse {
  * API would reject the same value the same way.
  */
 export const IDEMPOTENCY_KEY_CONSTRAINTS = {
+  /**
+   * HTTP header name. Here for the same reason {@link CALLER.HEADER} is: a
+   * wire header has two ends, and the package that owns the value's format
+   * is the only place both ends can read its name from.
+   */
+  HEADER: 'Idempotency-Key',
   MAX_LENGTH: 256,
   /** How long a stored 201 stays replayable. */
   WINDOW_SECONDS: 24 * 60 * 60,
 } as const;
 
+/**
+ * Normalize a `via` value from any transport — trimmed, lowercased, and a
+ * member of {@link DeploymentVia}, or `undefined`.
+ *
+ * A format rule by this package's own test: a client can decide offline
+ * whether a value is well-formed, and the API reaches the same verdict on the
+ * same input. It lived server-side until 2026-08-06, which meant clients could
+ * only learn their label was unusable by noticing analytics had gone quiet.
+ *
+ * **Not knowing your `via` is not an error** — an unrecognized value yields
+ * `undefined` rather than throwing, because origin tracking is telemetry and a
+ * deploy must never fail over it. A caller that has an honest default should
+ * prefer it (`normalizeVia(process.env.SHIP_VIA) ?? DeploymentVia.CLI`): the
+ * deploy really did come from the CLI, so recording that beats recording
+ * nothing.
+ */
+export function normalizeVia(value: unknown): DeploymentViaType | undefined {
+  if (!value || typeof value !== 'string') return undefined;
+  const via = value.trim().toLowerCase();
+  return (Object.values(DeploymentVia) as string[]).includes(via)
+    ? (via as DeploymentViaType)
+    : undefined;
+}
+
 /**
  * Validate an idempotency key, returning the trimmed value or `undefined`
  * when none was supplied. Throws {@link ShipError.validation} when the value
@@ -1811,8 +1873,12 @@ export type DeployInput = File[] | string | string[];
 export interface DeploymentUploadOptions {
   /** Optional labels for categorization and filtering */
   labels?: string[];
-  /** Client identifier (e.g., 'cli', 'sdk', 'web') */
-  via?: string;
+  /**
+   * Which client is making this deploy. Closed, because the server silently
+   * ignores anything outside the set — so an unchecked string turned a typo
+   * into missing analytics rather than an error. See {@link DeploymentVia}.
+   */
+  via?: DeploymentViaType;
   /**
    * Optional password that protects this deployment.
    *