@shipstatic/ship 0.8.5 → 0.8.7

package/README.md

@@ -1,6 +1,6 @@
 # @shipstatic/ship
 
-Universal SDK and CLI for deploying static files to ShipStatic.
+Universal SDK and CLI for deploying static sites to ShipStatic. No account required — deploy instantly, claim later.
 
 ## Installation
 
@@ -15,7 +15,7 @@ npm install @shipstatic/ship
 ## CLI Usage
 
 ```bash
-# Deploy a directory
+# Deploy — no account needed, site is live instantly
 ship ./dist
 
 # Deploy with labels
@@ -25,6 +25,8 @@ ship ./dist --label production --label v1.0.0
 ship ./dist -q | ship domains set www.example.com
 ```
 
+Without credentials, deployments are public (3-day TTL) with a claim URL. Configure an API key for permanent deployments: `ship config`
+
 ### Composability
 
 The `-q` flag outputs only the resource identifier — perfect for piping and scripting:
@@ -107,27 +109,22 @@ ship completion uninstall
 ```javascript
 import Ship from '@shipstatic/ship';
 
-const ship = new Ship({
-  apiKey: 'ship-your-api-key'
-});
-
-// Deploy (shortcut)
+// Deploy — no credentials needed
+const ship = new Ship();
 const deployment = await ship.deploy('./dist');
-console.log(`Deployed: https://${deployment.deployment}`);
+console.log(`Live: https://${deployment.deployment}`);
+console.log(`Claim: ${deployment.claim}`); // User visits to keep permanently
 
-// Deploy with options
-const deployment = await ship.deployments.upload('./dist', {
+// With an API key — deployments are permanent
+const ship = new Ship({ apiKey: 'ship-your-api-key' });
+const deployment = await ship.deploy('./dist', {
   labels: ['production', 'v1.0'],
   onProgress: ({ percent }) => console.log(`${percent}%`)
 });
 
-// Manage domains
+// Manage domains (requires API key)
 await ship.domains.set('www.example.com', { deployment: deployment.deployment });
 await ship.domains.list();
-
-// Update labels
-await ship.deployments.set(deployment.deployment, { labels: ['production', 'v1.0'] });
-await ship.domains.set('www.example.com', { labels: ['live'] });
 ```
 
 ## Browser Usage
@@ -149,6 +146,8 @@ const deployment = await ship.deploy([
 
 ## Authentication
 
+Deploying works without credentials. For permanent deployments and account features:
+
 ```javascript
 // API key (persistent access)
 const ship = new Ship({
@@ -330,6 +329,10 @@ import type {
 } from '@shipstatic/types';
 ```
 
+## AI Agents
+
+This package includes a [SKILL.md](./SKILL.md) file — a portable skill definition that AI agents (Claude Code, Codex, OpenClaw, etc.) use to deploy sites with `ship` autonomously.
+
 ---
 
 Part of the [ShipStatic](https://shipstatic.com) platform.

package/SKILL.md

@@ -1,14 +1,12 @@
 ---
 name: ship
-description: Static hosting via ShipStatic. Use when the user wants to deploy a website, upload files, manage deployments, set up domains, or publish static files to shipstatic.com.
+description: "Deploy static websites to ShipStatic. Use when the user wants to deploy a site, publish a website, upload to hosting, go live, set up a custom domain, manage deployments, or share a site URL. No account required — instant deployment. CLI (`ship`) and Node.js/browser SDK."
+compatibility: "Node.js >= 20. Install globally via npm: npm install -g @shipstatic/ship"
 metadata:
   openclaw:
     requires:
-      env:
-        - SHIP_API_KEY
       bins:
         - ship
-    primaryEnv: SHIP_API_KEY
     emoji: "🚀"
     homepage: https://github.com/shipstatic/ship
     install:
@@ -17,163 +15,254 @@ metadata:
         bins: [ship]
 ---
 
-## Authenticate
+Deploy static sites. No account, no config — just ship it.
+
+## Deploy
 
 ```bash
-ship config                    # Interactive — saves to ~/.shiprc
-ship --api-key <key> ...       # Per-command
-export SHIP_API_KEY=<key>      # Environment variable
+ship ./dist
 ```
 
-Get an API key at https://my.shipstatic.com/settings
+Site is live. Output includes the URL and a claim link.
 
-## Output Modes
+Pass a build output directory (e.g. `./dist`, `./build`, `./out`) or a single file. Ship strips the directory prefix for clean URLs — `dist/assets/app.js` serves at `/assets/app.js`. A single file keeps its name: `ship page.html` deploys as `/page.html`. Deploying a project root (contains `package.json`, `node_modules`) is rejected — build first, then deploy the output.
 
-Every command supports three output modes:
+Without credentials, deployments are public and expire in 3 days. **Always show the user both the deployment URL and the claim link** — the claim link lets them keep the site permanently.
 
-| Flag | Purpose | Use when |
-|------|---------|----------|
-| (default) | Human-readable text | Showing results to the user |
-| `--json` | Raw JSON on stdout | Parsing output programmatically |
-| `-q` | Key identifier only | Piping between commands |
+The deployment ID **is** the URL hostname. Use the full ID (e.g. `happy-cat-abc1234.shipstatic.com`) as the argument to all other commands. The site lives at `https://<deployment>`.
 
-Always use `--json` when you need to parse output. Always use `-q` when piping between commands.
+### Parsing output
 
-Errors go to stderr in all modes. Exit code 0 = success, 1 = error.
+```bash
+ship ./dist --json
+```
 
-## Deploy
+```json
+{
+  "deployment": "happy-cat-abc1234.shipstatic.com",
+  "files": 12,
+  "size": 348160,
+  "status": "success",
+  "config": false,
+  "labels": [],
+  "via": "cli",
+  "created": 1743552000,
+  "expires": 1743811200,
+  "claim": "https://my.shipstatic.com/claim/abc123"
+}
+```
+
+`claim` and `expires` only appear without credentials. With an API key, deployments are permanent.
+
+### Piping
 
 ```bash
-ship ./dist                              # Deploy a directory or file
-ship ./dist --json                       # Parse: {"deployment": "happy-cat-abc1234.shipstatic.com", ...}
-ship ./dist -q                           # Outputs only: happy-cat-abc1234.shipstatic.com
-ship ./dist --label v1.0 --label latest  # Labels (repeatable, replaces all existing)
+ship ./dist -q              # → happy-cat-abc1234.shipstatic.com
 ```
 
-Deployment IDs are their permanent URLs: `word-word-hash.shipstatic.com`. Always use the full ID (including `.shipstatic.com`) as the argument to other commands.
+`-q` outputs only the identifier — use it when piping or scripting.
 
-## Custom Domain Setup (full workflow)
+### Labels
 
 ```bash
-# 1. Pre-flight check (exit 0 = valid, exit 1 = invalid)
+ship ./dist --label v1.0 --label production
+```
+
+Labels **replace all existing**, not append. Include current labels to keep them.
+
+### SPA routing
+
+Ship auto-detects single-page apps from `index.html` content and configures client-side routing rewrites — all paths serve `index.html`. No action needed. Skipped if a `ship.json` config is already included in the deployment. Disable with `--no-spa-detect`.
+
+## Authentication
+
+Deploy works without credentials. Everything else requires an API key.
+
+| Needs API key | No auth needed |
+|---------------|----------------|
+| Permanent deploys, domains, tokens, account | Deploy (public, 3-day TTL) |
+
+```bash
+export SHIP_API_KEY=<key>          # Environment variable (best for automation)
+ship --api-key <key> ...           # Per-command override
+ship config                        # Interactive setup → ~/.shiprc (requires TTY)
+```
+
+Deploy tokens (`--deploy-token`) are single-use — consumed after one successful deploy. For CI/CD one-shot workflows.
+
+Free API key: https://my.shipstatic.com/api-key
+
+## Custom Domains
+
+Requires an API key. Full workflow:
+
+```bash
+# 1. Validate
 ship domains validate www.example.com
 
-# 2. Deploy and link in one pipe
+# 2. Deploy + link in one pipe
 ship ./dist -q | ship domains set www.example.com
 
-# 3. Get the required DNS records (to show the user)
+# 3. Show DNS records to the user
 ship domains records www.example.com
 
-# 4. After user configures DNS, trigger verification
+# 4. After user configures DNS → verify
 ship domains verify www.example.com
 ```
 
-In text mode, step 2 automatically prints the DNS records and a shareable setup link when creating a new external domain. In `--json` mode it does not — use `domains records` separately.
+Step 2 auto-prints DNS records and a setup link in text mode. With `--json`, call `domains records` separately.
+
+Verification is async — DNS propagation takes minutes to hours. Check status with `ship domains get <name> --json` and look for `"status": "success"`.
+
+### Domain types
+
+| Type | Example | DNS needed | Goes live |
+|------|---------|------------|-----------|
+| Internal | `my-site.shipstatic.com` | No | Instantly |
+| Custom | `www.example.com` | CNAME + A | After DNS verified |
+
+**No apex domains.** Always `www.example.com`, not `example.com`. The A record only redirects apex to www.
+
+### Upsert operations
+
+`domains set` creates if new, updates if exists:
 
-Additional setup helpers (external domains only):
 ```bash
-ship domains dns www.example.com         # DNS provider name (where to configure)
-ship domains share www.example.com       # Shareable setup link for the user
+ship domains set www.example.com                   # Reserve (no deployment yet)
+ship domains set www.example.com <deployment>       # Link to deployment
+ship domains set www.example.com <other-dep>        # Switch (instant rollback)
+ship domains set www.example.com --label prod       # Update labels
 ```
 
-## Domain Types
+Reads deployment from stdin when piped: `ship ./dist -q | ship domains set www.example.com`
 
-| Type | Example | DNS required | Status |
-|------|---------|-------------|--------|
-| Internal subdomain | `my-site.shipstatic.com` | No | Instant (`success`) |
-| Custom subdomain | `www.example.com` | Yes (CNAME + A) | Starts `pending` until DNS verified |
+**No unlinking.** Once linked, switch deployments or delete the domain. Setting deployment to null returns 400.
 
-**Apex domains are not supported.** Always use a subdomain: `www.example.com`, not `example.com`. The A record exists only to redirect `example.com` to `www.example.com`.
+### Parsing domain output
 
-## Domain Operations
+```bash
+ship domains set www.example.com <dep> --json
+```
 
-`domains set` is an upsert — creates if new, updates if exists:
+```json
+{
+  "domain": "www.example.com",
+  "deployment": "happy-cat-abc1234.shipstatic.com",
+  "status": "pending",
+  "labels": [],
+  "created": 1743552000,
+  "linked": 1743552000,
+  "links": 1
+}
+```
 
 ```bash
-ship domains set www.example.com                  # Reserve (no deployment)
-ship domains set www.example.com <deployment>      # Link to deployment
-ship domains set www.example.com <other-dep>       # Switch (instant rollback)
-ship domains set www.example.com --label prod      # Update labels
+ship domains records www.example.com --json
 ```
 
-`domains set` reads deployment from stdin when piped:
+```json
+{
+  "domain": "www.example.com",
+  "apex": "example.com",
+  "records": [
+    {"type": "A", "name": "@", "value": "76.76.21.21"},
+    {"type": "CNAME", "name": "www", "value": "cname.shipstatic.com"}
+  ]
+}
+```
+
+### DNS helpers (custom domains only)
+
 ```bash
-ship ./dist -q | ship domains set www.example.com
+ship domains dns www.example.com                  # Provider name
+ship domains share www.example.com                # Shareable setup link
+ship domains records www.example.com -q           # TYPE NAME VALUE (one per line)
 ```
 
-`domains validate` uses exit codes as the answer (the `grep`/`test` convention):
+### Validation
+
+Exit codes as the answer:
+
 ```bash
 ship domains validate www.example.com -q && echo "valid" || echo "invalid"
-# valid → exit 0, outputs normalized name
-# invalid → exit 1, no output
 ```
 
-## Important Behaviors
+Exit 0 = valid (outputs normalized name). Exit 1 = invalid (no output).
+
+## Output Modes
+
+Every command supports three modes:
+
+| Flag | Output | When to use |
+|------|--------|-------------|
+| *(default)* | Human-readable | Showing results to the user |
+| `--json` | JSON on stdout | Parsing programmatically |
+| `-q` | Identifier only | Piping between commands |
+
+Errors go to stderr in all modes. Exit 0 = success, 1 = error.
 
-- **Labels replace, not append.** `--label foo --label bar` sets labels to `["foo", "bar"]`, removing any existing labels. To keep existing labels, include them in the command.
-- **`records` quiet mode** outputs one record per line, space-separated: `TYPE NAME VALUE`. Parseable with awk: `ship domains records <name> -q | awk '{print $3}'` extracts values.
-- **`domains list` text mode** does not show domain status. Use `--json` to see which domains are `pending` vs `success`.
+List commands return `{"<resource>s": [...], "cursor": null, "total": N}`. `domains list` text mode omits status — use `--json` to see `pending` vs `success`.
 
-## Command Reference
+## Commands
 
 ### Deployments
 
 ```bash
-ship ./dist                          # Shortcut for deployments upload
-ship deployments upload <path>       # Upload directory or file
-ship deployments list                # List all deployments
-ship deployments get <deployment>    # Show deployment details
+ship ./dist                          # Deploy (shortcut)
+ship deployments upload <path>       # Deploy (explicit)
+ship deployments list                # List all
+ship deployments get <deployment>    # Details
 ship deployments set <deployment>    # Update labels (--label)
-ship deployments remove <deployment> # Delete permanently (async)
+ship deployments remove <deployment> # Delete (async)
 ```
 
 ### Domains
 
 ```bash
-ship domains list                     # List all domains
-ship domains get <name>               # Show domain details
-ship domains set <name> [deployment]  # Create, link, or update labels
-ship domains validate <name>          # Pre-flight check (exit 1 if invalid)
-ship domains records <name>           # Required DNS records (external only)
-ship domains dns <name>               # DNS provider lookup (external only)
-ship domains share <name>             # Shareable setup link (external only)
-ship domains verify <name>            # Trigger DNS verification (external only)
-ship domains remove <name>            # Delete permanently
+ship domains list                     # List all
+ship domains get <name>               # Details
+ship domains set <name> [deployment]  # Create, link, or update
+ship domains validate <name>          # Check validity (exit code)
+ship domains records <name>           # Required DNS records
+ship domains dns <name>               # DNS provider lookup
+ship domains share <name>             # Shareable setup link
+ship domains verify <name>            # Trigger DNS verification
+ship domains remove <name>            # Delete
 ```
 
 ### Account & Tokens
 
 ```bash
 ship whoami                           # Account info
-ship ping                             # API connectivity check
-ship tokens create                    # Create deploy token (secret shown once)
+ship ping                             # Connectivity check
+ship tokens create                    # New deploy token (shown once)
 ship tokens create --ttl 3600         # With expiry (seconds)
-ship tokens list                      # List tokens (management IDs only)
-ship tokens remove <token>            # Delete token
+ship tokens list                      # List tokens
+ship tokens remove <token>            # Revoke
 ```
 
-## Global Flags
+## Flags
 
 | Flag | Purpose |
 |------|---------|
 | `--json` | JSON output |
-| `-q, --quiet` | Key identifier only |
+| `-q, --quiet` | Identifier only |
 | `--api-key <key>` | API key for this command |
 | `--deploy-token <token>` | Single-use deploy token |
-| `--label <label>` | Set label (repeatable, replaces all existing) |
-| `--no-path-detect` | Disable build output auto-detection |
-| `--no-spa-detect` | Disable SPA rewrite auto-configuration |
-| `--no-color` | Plain text output |
-| `--config <file>` | Custom config file path |
-
-## Error Patterns
-
-| Error | Meaning | Action |
-|-------|---------|--------|
-| `authentication required` | No credentials | Use `--api-key`, `--deploy-token`, or `ship config` |
-| `authentication failed` | Invalid credentials | Check key/token validity |
-| `not found` | Resource doesn't exist | Verify the ID/name |
-| `path does not exist` | Deploy path invalid | Check the file/directory path |
-| `invalid domain name` | Bad domain format | Must be a subdomain (e.g., `www.example.com`) |
-| `DNS information is only available for external domains` | Used records/dns/share on `*.shipstatic.com` | Only custom domains need DNS setup |
-| `DNS verification already requested recently` | Rate limited | Wait and retry |
+| `--label <label>` | Set label (repeatable, replaces all) |
+| `--no-path-detect` | Skip build output auto-detection |
+| `--no-spa-detect` | Skip SPA rewrite auto-configuration |
+| `--no-color` | Disable colors |
+| `--config <file>` | Custom config path |
+
+## Errors
+
+| Message | Cause | Fix |
+|---------|-------|-----|
+| `too many requests` | Rate limited | Wait, or set an API key |
+| `authentication failed` | Bad credentials | Check key/token |
+| `not found` | No such resource | Verify the ID/name |
+| `path does not exist` | Bad deploy path | Check file/directory |
+| `invalid domain name` | Not a subdomain | Use `www.example.com`, not `example.com` |
+| `DNS information is only available for external domains` | DNS op on internal domain | Only custom domains need DNS |
+| `DNS verification already requested recently` | Rate limited | Wait |

package/dist/browser.d.ts

@@ -1,5 +1,5 @@
 import * as _shipstatic_types from '@shipstatic/types';
-import { DeploymentUploadOptions, ProgressInfo, StaticFile, Domain, Deployment, DeploymentListResponse, DomainListResponse, DomainDnsResponse, DomainRecordsResponse, DomainValidateResponse, TokenCreateResponse, TokenListResponse, Account, ConfigResponse, ResolvedConfig, DeployInput, AccountResource, DeploymentResource, DomainResource, TokenResource, ValidatableFile, FileValidationResult } from '@shipstatic/types';
+import { DeploymentUploadOptions, ProgressInfo, StaticFile, Domain, DeploymentCreateResponse, DeploymentListResponse, Deployment, DomainListResponse, DomainDnsResponse, DomainRecordsResponse, DomainValidateResponse, TokenCreateResponse, TokenListResponse, Account, ConfigResponse, ResolvedConfig, DeployInput, AccountResource, DeploymentResource, DomainResource, TokenResource, ValidatableFile, FileValidationResult } from '@shipstatic/types';
 export * from '@shipstatic/types';
 export { Account, AccountResource, DEFAULT_API, DeployInput, Deployment, DeploymentResource, Domain, DomainResource, ErrorType, FileValidationStatus as FILE_VALIDATION_STATUS, PingResponse, ResolvedConfig, ShipError, StaticFile, TokenResource } from '@shipstatic/types';
 
@@ -208,7 +208,7 @@ declare class ApiHttp extends SimpleEvents {
     private parseResponse;
     private handleResponseError;
     private handleFetchError;
-    deploy(files: StaticFile[], options?: ApiDeployOptions): Promise<Deployment>;
+    deploy(files: StaticFile[], options?: ApiDeployOptions): Promise<DeploymentCreateResponse>;
     listDeployments(): Promise<DeploymentListResponse>;
     getDeployment(id: string): Promise<Deployment>;
     updateDeploymentLabels(id: string, labels: string[]): Promise<Deployment>;
@@ -230,6 +230,7 @@ declare class ApiHttp extends SimpleEvents {
     createToken(ttl?: number, labels?: string[]): Promise<TokenCreateResponse>;
     listTokens(): Promise<TokenListResponse>;
     removeToken(token: string): Promise<void>;
+    fetchAgentToken(): Promise<TokenCreateResponse>;
     getAccount(): Promise<Account>;
     getConfig(): Promise<ConfigResponse>;
     ping(): Promise<boolean>;
@@ -676,7 +677,7 @@ declare function getCurrentConfig(): ConfigResponse;
  * - **Server-processed** (build/prerender): Source files destined for server-side build.
  *   Junk filtering and MD5 checksums only — the build service validates the output.
  *
- * Both modes share: environment check → extract paths → filter junk → optimize paths → MD5.
+ * Both modes share: environment check → extract paths → optimize paths → filter junk → MD5.
  */
 
 /**