@portalshq/capability-identity 0.1.2 → 0.2.0

package/README.md

@@ -1,5 +1,33 @@
 # @portalshq/capability-identity
 
-Cross-channel audience identity. Every other capability that needs to know
-"who is this audience member" depends on this rather than rolling its own
-auth — that's the only way a persistent cross-channel profile is possible.
+**Reusable agent module:** [integration guide](../../../docs/package-agents/identity.md)
+
+Verified application identity and persistent cross-channel interaction history.
+
+## Exported shape
+
+- `AudienceIdentity`: `userId` and `displayName`.
+- `ChannelInteraction`: soft `channelId` and `sessionId` cross-database keys.
+- `ChannelHistoryEntry`: a `ChannelInteraction` plus the stored interaction time.
+- `IdentityProvider`: `getIdentity()`, `recordInteraction()`, `getHistory()` — each verifies an access token first.
+- `IdentityStore`: persistence contract, so applications can substitute their own storage.
+- `PostgresIdentityStore`: adapter for Portals `application_users` and `application_user_channel_history`.
+- `QueryRunner`: the minimal `pg.Pool` surface the adapter needs.
+
+## Setup
+
+Portals operators apply `frontend/migrations/015_application_user_channel_history.sql`; creator
+applications do not own or run this migration. Construct the provider with a token verifier that
+validates the credential server-side and returns an active `application_users.id`, plus a
+`PostgresIdentityStore`. Never let a browser-supplied user ID be the verifier's result.
+
+## Limits
+
+- Interaction time is the storage transaction clock, so a caller cannot backdate or forward-date history.
+- `channelId` and `sessionId` are 1–128 characters, enforced in code and by the table.
+- `getHistory` reads at most `DEFAULT_HISTORY_ENTRIES` (100) rows and clamps any request to `MAX_HISTORY_ENTRIES` (500).
+
+## Tests
+
+`npm test` runs the provider and store unit tests. The PostgreSQL integration suite runs only when
+`IDENTITY_TEST_DATABASE_URL` points at a scratch database, because it creates and drops its own tables.

package/dist/identity-provider.d.ts

@@ -9,13 +9,32 @@ export interface AudienceIdentity {
     userId: string;
     displayName: string;
 }
-export interface ChannelHistoryEntry {
+/** Soft cross-database key; the matching channel row may live elsewhere. */
+export interface ChannelInteraction {
     channelId: string;
     sessionId: string;
+}
+export interface ChannelHistoryEntry extends ChannelInteraction {
     lastInteractionAt: string;
 }
+/** Matches the identifier bounds in the platform migration. */
+export declare const MAX_IDENTIFIER_LENGTH = 128;
+export declare const MAX_HISTORY_ENTRIES = 500;
+export declare const DEFAULT_HISTORY_ENTRIES = 100;
+export declare const INACTIVE_ACCOUNT_ERROR = "The verified user is not linked to an active application account.";
+export interface IdentityStore {
+    getIdentity(userId: string): Promise<AudienceIdentity | undefined>;
+    recordInteraction(userId: string, interaction: ChannelInteraction): Promise<void>;
+    getHistory(userId: string, limit: number): Promise<readonly ChannelHistoryEntry[]>;
+}
+/** Must validate the credential and return an active application user ID. */
+export type VerifyAccessToken = (accessToken: string) => Promise<string>;
 export declare class IdentityProvider {
-    getIdentity(userId: string): Promise<AudienceIdentity>;
-    recordInteraction(entry: ChannelHistoryEntry): Promise<void>;
-    getHistory(userId: string): Promise<ChannelHistoryEntry[]>;
+    private readonly verifyAccessToken;
+    private readonly store;
+    constructor(verifyAccessToken: VerifyAccessToken, store: IdentityStore);
+    getIdentity(accessToken: string): Promise<AudienceIdentity>;
+    /** Interaction time is the storage transaction's clock, never the caller's. */
+    recordInteraction(accessToken: string, interaction: ChannelInteraction): Promise<void>;
+    getHistory(accessToken: string, limit?: number): Promise<readonly ChannelHistoryEntry[]>;
 }

package/dist/identity-provider.js

@@ -1,11 +1,42 @@
+/** Matches the identifier bounds in the platform migration. */
+export const MAX_IDENTIFIER_LENGTH = 128;
+export const MAX_HISTORY_ENTRIES = 500;
+export const DEFAULT_HISTORY_ENTRIES = 100;
+export const INACTIVE_ACCOUNT_ERROR = "The verified user is not linked to an active application account.";
 export class IdentityProvider {
-    async getIdentity(userId) {
-        throw new Error("IdentityProvider.getIdentity: not yet implemented");
+    verifyAccessToken;
+    store;
+    constructor(verifyAccessToken, store) {
+        this.verifyAccessToken = verifyAccessToken;
+        this.store = store;
     }
-    async recordInteraction(entry) {
-        throw new Error("IdentityProvider.recordInteraction: not yet implemented");
+    async getIdentity(accessToken) {
+        const userId = await this.verifyAccessToken(accessToken);
+        const identity = await this.store.getIdentity(userId);
+        if (!identity)
+            throw new Error(INACTIVE_ACCOUNT_ERROR);
+        return identity;
     }
-    async getHistory(userId) {
-        throw new Error("IdentityProvider.getHistory: not yet implemented");
+    /** Interaction time is the storage transaction's clock, never the caller's. */
+    async recordInteraction(accessToken, interaction) {
+        assertIdentifier(interaction.channelId, "channelId");
+        assertIdentifier(interaction.sessionId, "sessionId");
+        const identity = await this.getIdentity(accessToken);
+        await this.store.recordInteraction(identity.userId, interaction);
     }
+    async getHistory(accessToken, limit = DEFAULT_HISTORY_ENTRIES) {
+        const identity = await this.getIdentity(accessToken);
+        return this.store.getHistory(identity.userId, historyLimit(limit));
+    }
+}
+function assertIdentifier(value, field) {
+    const trimmed = value?.trim() ?? "";
+    if (!trimmed || trimmed.length > MAX_IDENTIFIER_LENGTH) {
+        throw new TypeError(`${field} must be 1-${MAX_IDENTIFIER_LENGTH} characters.`);
+    }
+}
+function historyLimit(limit) {
+    if (!Number.isInteger(limit) || limit < 1)
+        throw new TypeError("History limit must be a positive integer.");
+    return Math.min(limit, MAX_HISTORY_ENTRIES);
 }

package/dist/index.d.ts

@@ -1 +1,2 @@
 export * from "./identity-provider.js";
+export * from "./postgres-store.js";

package/dist/index.js

@@ -1 +1,2 @@
 export * from "./identity-provider.js";
+export * from "./postgres-store.js";

package/dist/postgres-store.d.ts

@@ -0,0 +1,20 @@
+import { type AudienceIdentity, type ChannelHistoryEntry, type ChannelInteraction, type IdentityStore } from "./identity-provider.js";
+/** Minimal shape of `pg.Pool`, so the published types need no pg typings. */
+export interface QueryRunner {
+    query(text: string, values?: unknown[]): Promise<{
+        rowCount: number | null;
+        rows: Array<Record<string, unknown>>;
+    }>;
+}
+export declare class PostgresIdentityStore implements IdentityStore {
+    private readonly pool;
+    constructor(pool: QueryRunner);
+    getIdentity(userId: string): Promise<AudienceIdentity | undefined>;
+    /**
+     * The active-account check and the write are one statement, so a suspension
+     * can never land between them. GREATEST keeps the newest interaction when
+     * concurrent transactions commit out of order.
+     */
+    recordInteraction(userId: string, interaction: ChannelInteraction): Promise<void>;
+    getHistory(userId: string, limit: number): Promise<readonly ChannelHistoryEntry[]>;
+}

package/dist/postgres-store.js

@@ -0,0 +1,39 @@
+import { INACTIVE_ACCOUNT_ERROR, } from "./identity-provider.js";
+export class PostgresIdentityStore {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    async getIdentity(userId) {
+        const result = await this.pool.query("SELECT id, display_name FROM application_users WHERE id = $1 AND status = 'active'", [userId]);
+        const row = result.rows[0];
+        return row ? { userId: String(row.id), displayName: String(row.display_name) } : undefined;
+    }
+    /**
+     * The active-account check and the write are one statement, so a suspension
+     * can never land between them. GREATEST keeps the newest interaction when
+     * concurrent transactions commit out of order.
+     */
+    async recordInteraction(userId, interaction) {
+        const result = await this.pool.query(`INSERT INTO application_user_channel_history (user_id, channel_id, session_id, last_interaction_at)
+       SELECT $1, $2, $3, now()
+       WHERE EXISTS (SELECT 1 FROM application_users WHERE id = $1 AND status = 'active')
+       ON CONFLICT (user_id, channel_id, session_id) DO UPDATE
+       SET last_interaction_at = GREATEST(application_user_channel_history.last_interaction_at, EXCLUDED.last_interaction_at)`, [userId, interaction.channelId, interaction.sessionId]);
+        if (!result.rowCount)
+            throw new Error(INACTIVE_ACCOUNT_ERROR);
+    }
+    async getHistory(userId, limit) {
+        const result = await this.pool.query(`SELECT channel_id, session_id, last_interaction_at
+       FROM application_user_channel_history
+       WHERE user_id = $1 ORDER BY last_interaction_at DESC LIMIT $2`, [userId, limit]);
+        return result.rows.map(historyFromRow);
+    }
+}
+function historyFromRow(row) {
+    return {
+        channelId: String(row.channel_id),
+        sessionId: String(row.session_id),
+        lastInteractionAt: new Date(row.last_interaction_at).toISOString(),
+    };
+}

package/package.json

@@ -1,28 +1,30 @@
 {
   "name": "@portalshq/capability-identity",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/portalshq/portals-cloud.git",
-    "directory": "packages/stubs/identity"
+    "directory": "packages/capability-identity"
   },
   "description": "Federated audience identity, persistent across every channel — current and future, platform-provided and developer-created.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
-  },
-  "dependencies": {
-    "@portalshq/contracts": "*"
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
   },
   "devDependencies": {
     "typescript": "^5.5.0",
-    "@types/node": "^20.0.0"
+    "@types/node": "^20.0.0",
+    "@types/pg": "^8.15.5",
+    "pg": "^8.16.3",
+    "vitest": "^3.2.7"
   },
   "publishConfig": {
     "access": "public",