@hasna/contacts 0.6.22 → 0.6.27

package/dist/server/cloud.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Cloud (A1 pure-remote) service wiring for `contacts-serve`.
+ *
+ * This module powers the versioned `/v1` API and its API-key auth. Per Amendment
+ * A1 the serve process reads and writes the shared RDS Postgres DIRECTLY through
+ * the vendored @hasna/contracts storage kit — there is NO local sync/cache in
+ * the service. Everything is lazy: nothing touches Postgres or crypto until the
+ * first `/v1` / `/ready` request, so the local-first CLI/dashboard SQLite paths
+ * keep ZERO cloud dependencies.
+ */
+import { ApiKeyStore, type ApiKeyVerifier } from "@hasna/contracts/auth";
+import type { PoolQueryClient } from "../generated/storage-kit/query.js";
+export declare const CONTACTS_APP_SLUG = "contacts";
+/** Resolve the remote DATABASE_URL from the supported env vars (priority order). */
+export declare function resolveCloudDatabaseUrl(env?: NodeJS.ProcessEnv): string | undefined;
+/** Resolve the HMAC signing secret used to verify API keys. */
+export declare function resolveSigningSecret(env?: NodeJS.ProcessEnv): string | undefined;
+/** True when this process is configured to serve the cloud `/v1` API. */
+export declare function isCloudModeEnabled(env?: NodeJS.ProcessEnv): boolean;
+/** The vendored-kit Postgres pool client backing every `/v1` handler. */
+export declare function getCloudClient(): PoolQueryClient;
+export declare function getApiKeyStore(): ApiKeyStore;
+/**
+ * The framework-agnostic API-key verifier for `/v1`. Tokens are stateless,
+ * HMAC-signed by the contracts issuer; revocation is checked against the RDS
+ * `api_keys` table. Fails closed when no signing secret is configured.
+ */
+export declare function getCloudVerifier(): ApiKeyVerifier;
+/**
+ * Ensure the remote schema exists: the relational contacts schema (translated
+ * for Postgres in PG_MIGRATIONS) plus the contracts api-keys table. Idempotent —
+ * every statement is CREATE ... IF NOT EXISTS / ADD COLUMN IF NOT EXISTS /
+ * ON CONFLICT DO NOTHING. NEVER drops or rewrites existing tables.
+ */
+export declare function ensureCloudSchema(): Promise<void>;
+/**
+ * Runtime schema check for the request path. The `contacts-serve` service runs
+ * as the LEAST-PRIVILEGE app role (DML only, no DDL) per the RDS isolation
+ * model; the one-shot migration task owns all schema DDL as the OWNER role.
+ * So here we attempt the ensure exactly ONCE and, if the app role lacks DDL
+ * privileges (the expected steady state), log a single line and proceed — the
+ * schema is already present, applied by the migration task. This NEVER throws,
+ * so a permission boundary can't take the API down. In local/dev where serve
+ * runs with a privileged role, this self-heals the schema on first request.
+ */
+export declare function ensureCloudSchemaBestEffort(): Promise<void>;
+/** Cheap readiness probe: round-trips a trivial query to RDS. */
+export declare function pingCloud(): Promise<boolean>;
+/** Test/shutdown helper. */
+export declare function closeCloud(): Promise<void>;
+//# sourceMappingURL=cloud.d.ts.map

package/dist/server/cloud.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud.d.ts","sourceRoot":"","sources":["../../src/server/cloud.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAgB,WAAW,EAAE,KAAK,cAAc,EAAwB,MAAM,uBAAuB,CAAC;AAE7G,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAIzE,eAAO,MAAM,iBAAiB,aAAa,CAAC;AAE5C,oFAAoF;AACpF,wBAAgB,uBAAuB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,GAAG,SAAS,CAOhG;AAED,+DAA+D;AAC/D,wBAAgB,oBAAoB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,GAAG,SAAS,CAO7F;AAED,yEAAyE;AACzE,wBAAgB,kBAAkB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAEhF;AAQD,yEAAyE;AACzE,wBAAgB,cAAc,IAAI,eAAe,CA2BhD;AAYD,wBAAgB,cAAc,IAAI,WAAW,CAI5C;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,cAAc,CAejD;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAUvD;AAED;;;;;;;;;GASG;AACH,wBAAsB,2BAA2B,IAAI,OAAO,CAAC,IAAI,CAAC,CAYjE;AAED,iEAAiE;AACjE,wBAAsB,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC,CAGlD;AAED,4BAA4B;AAC5B,wBAAsB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAOhD"}