@hasna/shortlinks 0.1.22 → 0.1.24

package/README.md

@@ -1,8 +1,33 @@
 # @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, `@hasna/domains`, and `@hasna/cloud` sync. Production serving can run directly against the shared RDS database with `--cloud`; local SQLite is only for explicit local/offline use.
+`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)
@@ -64,7 +89,6 @@ shortlinks link enable home --domain has.na
 shortlinks stats home --domain has.na
 
 shortlinks serve --port 8787
-shortlinks serve --cloud --port 8787
 shortlinks doctor
 ```
 
@@ -125,36 +149,32 @@ shortlinks domain buy new-short-domain.ai --dry-run
 
 This package does not install or call any removed `connect-*` packages.
 
-## Cloud Sync
+## PostgreSQL Runtime
 
-`shortlinks` is compatible with `@hasna/cloud` conventions:
+Production serving can use a shortlinks-owned PostgreSQL database without any shared table-sync package:
 
 ```bash
-cloud setup
-shortlinks cloud migrate
-shortlinks cloud push
-shortlinks cloud pull
-shortlinks cloud sync
-```
+export HASNA_SHORTLINKS_STORE=postgres
+export HASNA_SHORTLINKS_DATABASE_URL=postgres://shortlinks:password@db.example.com:5432/shortlinks
+export HASNA_SHORTLINKS_DATABASE_SSL=true
 
-The cloud database service name is `shortlinks`.
-Use direct RDS mode for production and live management:
-
-```bash
-shortlinks --cloud create https://example.com
-shortlinks --cloud link list
-shortlinks serve --cloud --host 127.0.0.1 --port 8787
+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
 ```
 
+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 `shortlinks` RDS database through `@hasna/cloud`
+- direct reads and click writes against the app-owned `shortlinks` PostgreSQL database
 - Caddy terminating HTTPS and proxying to `shortlinks serve`
 
-The script reads the RDS password from AWS Secrets Manager through the instance role; it does not contain secret values.
+The script reads the connection settings from AWS Secrets Manager through the instance role; it does not contain secret values.
 
 ## Development