@hasna/shortlinks 0.1.23 → 0.2.0

package/README.md

@@ -1,9 +1,34 @@
 # @hasna/shortlinks
 
-CLI-only shortlink management for custom domains.
+Shortlink management for custom domains — CLI, MCP server, REST API, and a generated SDK.
 
 `shortlinks` creates Bitly-style short URLs, supports multiple domains, records click analytics, can run a tiny redirect server, and includes helper commands for Cloudflare DNS/Workers and `@hasna/domains`. It defaults to local SQLite and can serve from an app-owned PostgreSQL database when `HASNA_SHORTLINKS_STORE=postgres` and `HASNA_SHORTLINKS_DATABASE_URL` are configured.
 
+## Surfaces
+
+Four surfaces share one core library:
+
+| Surface | Bin / package | Purpose |
+| --- | --- | --- |
+| CLI | `shortlinks` | Interactive/scriptable link + domain management (`--json` for agents). |
+| MCP | `shortlinks-mcp` | Model Context Protocol server (stdio or `--http`) exposing link/domain tools to agents. |
+| REST API | `shortlinks-serve` | HTTP service: `GET /health`, `/ready`, `/version`, `/openapi.json`, and a versioned `/v1` CRUD API guarded by API-key auth. |
+| SDK | `@hasna/shortlinks-sdk` (+ `@hasna/shortlinks/sdk`) | Typed fetch client generated from the serve OpenAPI (`bun run sdk:generate`). |
+
+### Cloud service (PURE REMOTE, Amendment A1)
+
+`shortlinks-serve` reads/writes the shared cloud Postgres directly via the vendored `@hasna/contracts` storage kit — no sync engine or cache in the service. API-key auth comes from `@hasna/contracts/auth`; mint keys with `contracts issue-key --app shortlinks --scopes 'shortlinks:read,shortlinks:write'`.
+
+```bash
+HASNA_SHORTLINKS_STORAGE_MODE=cloud \
+HASNA_SHORTLINKS_DATABASE_URL=postgres://user:pass@host:5432/shortlinks?sslmode=require \
+HASNA_SHORTLINKS_API_SIGNING_KEY=... \
+shortlinks-serve            # migrate (idempotent) then serve on :8080
+shortlinks-serve migrate    # one-shot migration task
+```
+
+Client self_hosted mode uses `SHORTLINKS_API_URL` + `SHORTLINKS_API_KEY` (never a DSN).
+
 [![npm](https://img.shields.io/npm/v/@hasna/shortlinks)](https://www.npmjs.com/package/@hasna/shortlinks)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
 
@@ -124,32 +149,28 @@ shortlinks domain buy new-short-domain.ai --dry-run
 
 This package does not install or call any removed `connect-*` packages.
 
-## PostgreSQL Runtime
+## Storage modes
 
-Production serving can use a shortlinks-owned PostgreSQL database without any shared table-sync package:
+The client resolves ONE `Store` from the environment — there is no DSN on any client:
 
-```bash
-export HASNA_SHORTLINKS_STORE=postgres
-export HASNA_SHORTLINKS_DATABASE_URL=postgres://shortlinks:password@db.example.com:5432/shortlinks
-export HASNA_SHORTLINKS_DATABASE_SSL=true
+- **local** (default): on-box SQLite. Every command, MCP tool, and SDK call reads
+  and writes the local database.
+- **self_hosted / cloud**: set `HASNA_SHORTLINKS_API_URL` + `HASNA_SHORTLINKS_API_KEY`
+  (and optionally `HASNA_SHORTLINKS_STORAGE_MODE`) to route every call to the cloud
+  `/v1` HTTP API with a bearer key. `self_hosted` and `cloud` are identical client
+  code; only the URL/key differ.
 
-shortlinks postgres status
-shortlinks postgres plan --schema-sql
-shortlinks postgres migrate
-shortlinks --store postgres serve --host 127.0.0.1 --port 8787 --default-host has.na
+```bash
+# Route the client to the self-hosted cloud API (bearer key, never a DSN):
+export HASNA_SHORTLINKS_API_URL=https://shortlinks.hasna.xyz
+export HASNA_SHORTLINKS_API_KEY=hsk_...
+export HASNA_SHORTLINKS_STORAGE_MODE=self_hosted
+shortlinks doctor
 ```
 
-The canonical production runtime secret path is `hasna/xyz/opensource/shortlinks/prod/postgres`. Use the URL environment variables above rather than writing shared runtime config files into the shortlinks data directory.
-
-## AWS Origin
-
-For an apex domain that needs stable A records, `infra/aws-ec2-user-data.sh` bootstraps a small EC2 redirect origin with:
-
-- `@hasna/shortlinks` installed through Bun
-- direct reads and click writes against the app-owned `shortlinks` PostgreSQL database
-- Caddy terminating HTTPS and proxying to `shortlinks serve`
-
-The script reads the connection settings from AWS Secrets Manager through the instance role; it does not contain secret values.
+The cloud server (`shortlinks-serve`, run on ECS Fargate) is the only component
+that holds a Postgres connection, and it opens its pool server-side through the
+sanctioned storage kit — the raw RDS DSN is never distributed to clients.
 
 ## Development