# ShipStatic

> Static hosting on a global edge network. Deploy static sites in seconds, point a domain, go live.

## How It Works

The platform has two primitives:

- **Deployments** are immutable snapshots of static files. Each gets a unique ID (e.g. `pink-elephant-4ruf23f`) and an instant preview URL at `https://{id}.shipstatic.dev`. To update content, create a new deployment.
- **Domains** are pointers to deployments. Repoint a domain to any deployment instantly — that's how rollbacks work. Domains can be internal (`my-app.shipstatic.dev`) or custom (`www.example.com`).

Key URLs:

- Package: `@shipstatic/ship` (both CLI and SDK — same npm package)
- API: `https://api.shipstatic.com`
- Dashboard: `https://my.shipstatic.com`
- Docs: `https://docs.shipstatic.com`

## Authentication

All interfaces use the same credentials. Configure once, use everywhere.

**API key** — persistent, full account access, one per account.

- Format: `ship-{64 hex characters}`
- Find it: dashboard → Settings → API key
- Environment variable: `SHIP_API_KEY`
- Config file: `.shiprc` (created by `ship config`)
- HTTP header: `Authorization: Bearer ship-...`

**Deploy token** — single-use, deploy-only, expires with optional TTL.

- Format: `token-{64 hex characters}`
- Create via CLI: `ship tokens create --ttl 3600`
- HTTP header: `Authorization: Bearer token-...`
- Consumed on first deploy, then invalid

When both are present, the deploy token takes precedence.

## Quickstart

```bash
npm install -g @shipstatic/ship
ship config                        # enter API key once
ship ./dist                        # deploy — site is live
ship domains set my-app             # reserve internal domain
ship domains set my-app <id>        # link domain to deployment
```

---

## Deployments

### Properties

| Property | Description |
|----------|-------------|
| `deployment` | Unique identifier (e.g. `pink-elephant-4ruf23f`) |
| `url` | Preview URL (`https://{id}.shipstatic.dev`) |
| `files` | Number of files |
| `size` | Total size in bytes |
| `status` | `pending` → `success` or `failed`; then optionally `deleting` |
| `labels` | Mutable tags (3–63 chars, lowercase alphanumeric with `.`/`-`/`_`, max 10) |
| `via` | Creation method: `cli`, `sdk`, `web` |
| `created` | Creation timestamp |
| `expires` | Expiration timestamp (free-tier only) |

### Behaviors

- **Immutable.** Only labels can be modified after creation.
- **Path optimization.** Common root directories are flattened — `dist/index.html` → `index.html`.
- **SPA detection.** Detects React Router, Vue Router, etc. and configures client-side routing fallbacks automatically.

---

## Domains

### Properties

| Property | Description |
|----------|-------------|
| `domain` | Fully qualified domain name |
| `deployment` | Linked deployment ID, or `null` if reserved |
| `status` | DNS verification state: `pending`, `partial`, or `success` |
| `labels` | Mutable tags for organization |
| `verified` | When DNS was last verified |
| `created` | Creation timestamp |

### Internal domains

Subdomains of `shipstatic.dev` (e.g. `my-app.shipstatic.dev`).

- Instant — no DNS, no verification
- Name must be at least 6 characters
- Available on all plans

### Custom domains

Your own domain (e.g. `www.example.com`, `blog.example.com`).

- Requires DNS records pointing to the platform
- SSL provisioned automatically after verification
- Available on paid plans

### DNS verification

Internal domains are verified instantly. Custom domains require DNS verification:

| Status | Meaning |
|--------|---------|
| `pending` | No DNS records verified yet |
| `partial` | Some records found (e.g. CNAME but not A) |
| `success` | All records verified — domain is live |

**DNS records for `www` subdomains:**

| Type | Name | Purpose |
|------|------|---------|
| CNAME | `www` | Serves the site |
| A | `@` | Redirects apex to `www` (infrastructure only) |

**DNS records for other subdomains** (e.g. `blog`):

| Type | Name | Purpose |
|------|------|---------|
| CNAME | `blog` | Serves the site |

### Domain lifecycle

1. **Reserve** — `domains set <name>` (no deployment linked)
2. **Link** — `domains set <name> <deployment-id>`
3. **Switch** — `domains set <name> <other-deployment-id>` (instant rollback)
4. **Delete** — `domains remove <name>`

---

## ship.json

Optional configuration file in your project root. Most sites work without one.

### Clean URLs

```json
{ "cleanUrls": true }
```

`/about.html` is served at `/about`. Visiting `/about.html` redirects to `/about`.

### Trailing Slash

| Value | Behavior |
|-------|----------|
| `false` | `/about/` redirects to `/about` |
| `true` | `/about` redirects to `/about/` |
| not set | Both forms work |

### Redirects

```json
{
  "redirects": [
    { "source": "/pricing", "destination": "/plans", "permanent": true },
    { "source": "/blog/:slug", "destination": "/posts/:slug" }
  ]
}
```

Pattern syntax: `:param` matches one segment, `:path*` matches everything after. Default: `permanent: true` (308).

### Rewrites

Serve content from a different path without changing the URL. Files on disk take priority.

```json
{
  "rewrites": [
    { "source": "/feed", "destination": "/feed.xml" }
  ]
}
```

### Headers

```json
{
  "headers": [
    {
      "source": "/assets/(.*)",
      "headers": [
        { "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }
      ]
    }
  ]
}
```

### SPA Fallback

The platform automatically detects single-page apps and configures client-side routing fallbacks. Most SPAs work without any configuration. Use a manual rewrite only if auto-detection doesn't cover your setup:

```json
{
  "rewrites": [
    { "source": "/(.*)", "destination": "/index.html" }
  ]
}
```

### Processing Order

1. Static files (served if they exist)
2. Headers (all matching rules apply)
3. Redirects (checked before rewrites)
4. Rewrites (fallback when nothing else matched)

Within redirects and rewrites, rules are processed in array order. Put catch-all patterns last.

---

## Important Constraints

- **No apex domains.** `example.com` cannot be hosted — always use a subdomain like `www.example.com`.
- **No unlinking.** Once a domain is linked to a deployment, it cannot be set back to empty. Switch to a different deployment or delete the domain.
- **Internal domain minimum.** Names must be at least 6 characters.
- **Deploy tokens are single-use.** Each token is consumed on its first deploy and becomes invalid.
- **Labels format.** 3–63 lowercase alphanumeric characters with `.`, `-`, or `_` separators. Maximum 10 per resource.
- **Domain names are normalized.** Case-insensitive, Unicode-aware. `Example.COM` → `example.com`.

---

## CLI

```bash
npm install -g @shipstatic/ship
```

### Deploy

```bash
ship <path>                                    # deploy a directory
ship <path> --label production --label v1.0    # with labels
ship <path> --no-spa-detect --no-path-detect   # disable auto-detection
ship <path> --json                             # machine-readable output
```

### Deployments

```bash
ship deployments upload <path>
ship deployments list
ship deployments get <id>
ship deployments set <id> --label production
ship deployments remove <id>
```

### Domains

```bash
ship domains set <name>                   # reserve
ship domains set <name> <deployment>      # link or switch
ship domains set <name> --label prod      # update labels
ship domains list
ship domains get <name>
ship domains validate <name>              # pre-flight check
ship domains verify <name>                # trigger DNS verification
ship domains remove <name>
```

### Tokens

```bash
ship tokens create --ttl 3600 --label ci
ship tokens list
ship tokens remove <token>
```

### Account

```bash
ship whoami                               # current account
ship account get                          # same as whoami
ship ping                                 # API connectivity
ship config                               # setup wizard
ship completion install                   # shell completions
```

### Global Flags

| Flag | Description |
|------|-------------|
| `--api-key <key>` | Override API key |
| `--deploy-token <token>` | Use a single-use deploy token |
| `--config <file>` | Custom config file path |
| `--label <label>` | Add label (repeatable) |
| `--no-path-detect` | Disable root directory flattening |
| `--no-spa-detect` | Disable SPA detection |
| `--no-color` | Disable colored output |
| `--json` | JSON output |
| `--version` | Show version |

### Config Precedence

1. Command-line flags
2. Environment variables (`SHIP_API_KEY`, `SHIP_API_URL`)
3. `.shiprc` file
4. `package.json` `"ship"` key

---

## MCP Server

Model Context Protocol server for AI agents.

```bash
npx @shipstatic/mcp
```

### Setup

```json
{
  "mcpServers": {
    "shipstatic": {
      "command": "npx",
      "args": ["@shipstatic/mcp"],
      "env": { "SHIP_API_KEY": "ship-..." }
    }
  }
}
```

Claude Code: `claude mcp add shipstatic -e SHIP_API_KEY=ship-... -- npx -y @shipstatic/mcp`

### Tools

| Tool | Description |
|------|-------------|
| `deployments_upload` | Upload a directory or file as a new deployment |
| `deployments_list` | List all deployments |
| `deployments_get` | Get deployment details |
| `deployments_set` | Update deployment labels |
| `deployments_remove` | Delete a deployment |
| `domains_set` | Create, link, switch, or label a domain |
| `domains_list` | List all domains |
| `domains_get` | Get domain details |
| `domains_records` | Get required DNS records |
| `domains_validate` | Check if name is valid and available |
| `domains_verify` | Trigger DNS verification |
| `domains_remove` | Delete a domain |
| `whoami` | Current account info |

---

## SDK

Same npm package as CLI: `@shipstatic/ship`.

```bash
npm install @shipstatic/ship
```

### Quick Start

```js
import Ship from '@shipstatic/ship';

const ship = new Ship({ apiKey: 'ship-...' });
const deployment = await ship.deploy('./dist');
```

### Constructor

```js
new Ship({ apiKey: 'ship-...' });        // API key
new Ship({ deployToken: 'token-...' });  // deploy token

// Set after construction
ship.setApiKey('ship-...');
ship.setDeployToken('token-...');
```

Precedence: Deploy token → API key → Cookie (browser only).

### Deploy Options

```ts
await ship.deploy('./dist', {
  labels: ['production'],
  onProgress: ({ percent }) => console.log(`${percent}%`),
  signal: AbortSignal.timeout(30000),
  spaDetect: false,
  pathDetect: false,
  subdomain: 'my-site',
});
```

### Methods

```ts
// Deployments
ship.deployments.upload(path, options?)
ship.deployments.list()
ship.deployments.get(id)
ship.deployments.set(id, { labels })
ship.deployments.remove(id)

// Domains
ship.domains.set(name, { deployment?, labels? })
ship.domains.list()
ship.domains.get(name)
ship.domains.remove(name)
ship.domains.validate(name)
ship.domains.verify(name)
ship.domains.dns(name)
ship.domains.records(name)
ship.domains.share(name)

// Tokens
ship.tokens.create({ ttl?, labels? })
ship.tokens.list()
ship.tokens.remove(token)

// Account
ship.account.get()     // or ship.whoami()
ship.ping()            // returns boolean
ship.getConfig()       // platform config and plan limits
```

### Browser

```js
import Ship from '@shipstatic/ship';
const ship = new Ship({ apiKey: 'ship-...' });

await ship.deploy(fileInput.files);
await ship.deploy([
  { path: 'index.html', content: new Blob(['<html>...</html>']) }
]);
```

### Events

```js
ship.on('request', (url, init) => {});
ship.on('response', (response, url) => {});
ship.on('error', (error, url) => {});
```

### Error Handling

```js
import { isShipError } from '@shipstatic/types';

try {
  await ship.deploy('./dist');
} catch (error) {
  if (isShipError(error)) {
    error.isAuthError();
    error.isValidationError();
    error.isNetworkError();
    error.isFileError();
    error.isConfigError();
  }
}
```

### TypeScript

```ts
import type { ShipClientOptions, DeploymentOptions, ShipEvents } from '@shipstatic/ship';
import type { Deployment, Domain, Account, StaticFile } from '@shipstatic/types';
```

### Config Precedence

1. Constructor options
2. Environment variables (`SHIP_API_KEY`, `SHIP_API_URL`)
3. `.shiprc` file
4. `package.json` `"ship"` key

---

## Ship Action

```yaml
- uses: shipstatic/action@v1
  with:
    api-key: ${{ secrets.SHIP_API_KEY }}
    path: ./dist
```

### Inputs

| Input | Required | Default | Description |
|-------|----------|---------|-------------|
| `api-key` | Yes | — | ShipStatic API key |
| `path` | No | `.` | Directory to deploy |
| `domain` | No | — | Domain to link after deploy |
| `github-token` | No | — | Enables PR comments and GitHub Deployments |

### Outputs

| Output | Description |
|--------|-------------|
| `id` | Deployment ID |
| `url` | Deployment preview URL |

### Full Example

```yaml
name: Deploy
on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read
  deployments: write
  pull-requests: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run build
      - uses: shipstatic/action@v1
        id: deploy
        with:
          api-key: ${{ secrets.SHIP_API_KEY }}
          path: ./dist
          domain: ${{ github.event_name == 'push' && 'www.example.com' || '' }}
          github-token: ${{ secrets.GITHUB_TOKEN }}
```

---

## Ship Skill

A SKILL.md file that teaches AI coding agents to deploy via the CLI.

```bash
curl --create-dirs -so .claude/skills/ship/SKILL.md https://www.shipstatic.com/SKILL.md
```

Compatible with Claude Code, Gemini CLI, Cursor, GitHub Copilot, and 30+ tools via the Agent Skills open standard.

---

## REST API

```
https://api.shipstatic.com
```

### Endpoints

#### Deployments

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/deployments` | Upload new deployment (`multipart/form-data`) |
| `GET` | `/deployments` | List all deployments |
| `GET` | `/deployments/:id` | Get deployment details |
| `PATCH` | `/deployments/:id` | Update labels |
| `DELETE` | `/deployments/:id` | Delete deployment (async, returns `202`) |

#### Domains

| Method | Path | Description |
|--------|------|-------------|
| `PUT` | `/domains/:name` | Create, link, switch, or label (upsert) |
| `GET` | `/domains` | List all domains |
| `GET` | `/domains/:name` | Get domain details |
| `DELETE` | `/domains/:name` | Delete domain |
| `POST` | `/domains/:name/validate` | Pre-flight availability check |
| `POST` | `/domains/:name/verify` | Trigger DNS verification |
| `GET` | `/domains/:name/dns` | Required DNS records for setup |
| `GET` | `/domains/:name/records` | Current live DNS records |
| `GET` | `/domains/:name/share` | Shareable DNS setup link |

#### Tokens

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/tokens` | Create token |
| `GET` | `/tokens` | List all tokens |
| `DELETE` | `/tokens/:token` | Revoke token |

#### Account

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/account` | Current account details |
| `GET` | `/config` | Platform config and plan limits |
| `GET` | `/ping` | Health check |

### Status Codes

| Code | Meaning |
|------|---------|
| `200` | Success |
| `201` | Created (`POST /deployments`, `POST /tokens`) |
| `202` | Accepted (`DELETE /deployments/:id` — async cleanup) |
| `400` | Validation error |
| `401` | Authentication error |
| `404` | Not found |
| `422` | Business rule violation (suspended, limit exceeded) |
| `429` | Rate limited |

### Error Format

```json
{
  "error": "Deployment not found",
  "type": "not_found",
  "status": 404
}
```

### Conventions

- All requests/responses are `application/json` except deployment upload (`multipart/form-data`).
- Domain names in URL paths are URL-encoded. The API normalizes casing and Unicode.
- Only deployment deletion is async (`202`). All other mutations are synchronous.