@payez/next-mvp 4.8.3 → 4.8.4

package/README.md

@@ -499,6 +499,33 @@ export function Providers({ children }: { children: React.ReactNode }) {
 
 ---
 
+## Register an agent (REG-002)
+
+`@payez/next-mvp/agents` is a typed client over the tenant-admin agent door (`POST/GET api/client/agents`). The caller must be a tenant admin with completed MFA; the client (tenant) comes from the token, so there is no client id to pass.
+
+```ts
+import { createAgentRegistryClient, AgentRegistryError } from '@payez/next-mvp/agents';
+
+const agents = createAgentRegistryClient({
+  baseUrl: process.env.IDP_URL!,            // absolute origin of the identity service
+  accessToken: () => getAdminAccessToken(), // a string, or a function returning one
+});
+
+try {
+  const { item } = await agents.register({ user_name: 'build-bot', owner_user_id: 42, host_class: 'rig_pane' });
+  // item.status.code === 'PENDING': the first mint is refused AGENT_PENDING until an admin activates it.
+} catch (e) {
+  if (e instanceof AgentRegistryError) {
+    // e.code is Core's code as-is: VALIDATION_ERROR, OWNER_NOT_ELIGIBLE, OWNER_NOT_MEMBER, AGENT_NAME_TAKEN, ...
+    // e.status is the HTTP status (0 = no response). Nothing is retried; a 409 AGENT_NAME_TAKEN stays a 409.
+  }
+  throw e;
+}
+
+const { items } = await agents.list();  // every agent of your client
+const { item: one } = await agents.get(41);
+```
+
 ## API Routes
 
 Access pre-built API handlers:

package/dist/agents/index.d.ts

@@ -0,0 +1 @@
+export * from './registry';

package/dist/agents/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./registry"), exports);

package/dist/agents/registry.d.ts

@@ -0,0 +1,73 @@
+/** Core PayEzEndpoints.AgentTokens.AllowedHostClasses (PayEzEndpoints.cs:187,194,228). The server is the authority; this is for typing only. */
+export declare const AGENT_HOST_CLASSES: readonly ["rig_pane", "contractor"];
+export type AgentHostClass = (typeof AGENT_HOST_CLASSES)[number];
+export interface RegisterAgentInput {
+    /** 3-64 chars, letters/digits/'.'/'_'/'-', starting with a letter or digit; unique across the IdP. */
+    user_name: string;
+    /** A person (user id) who is an approved, active member of this client. */
+    owner_user_id: number;
+    host_class: AgentHostClass;
+}
+export interface AgentRecord {
+    id: number;
+    user_name: string;
+    owner: {
+        kind: 'person';
+        user_id: number;
+        display_name: string | null;
+        approved: boolean;
+    } | null;
+    status: {
+        code: string;
+        reason: string | null;
+    };
+    host_class: string | null;
+    agent_profile_id: number | null;
+}
+export interface MintableApp {
+    id: number;
+    name: string;
+    allowed_scopes: unknown;
+}
+export interface RegisterAgentResult {
+    item: AgentRecord | null;
+    created: boolean;
+    audited: boolean;
+}
+export interface ListAgentsResult {
+    client_id: number;
+    demo_token_ready: boolean | null;
+    items: AgentRecord[];
+    apps: MintableApp[];
+}
+export interface GetAgentResult {
+    item: AgentRecord;
+    apps: MintableApp[];
+}
+/** Codes this door is known to answer. `string` stays in the union: an unknown code is surfaced, not hidden. */
+export type AgentRegistryErrorCode = 'VALIDATION_ERROR' | 'OWNER_NOT_ELIGIBLE' | 'OWNER_NOT_MEMBER' | 'AGENT_NAME_TAKEN' | 'AUDIT_WRITE_FAILED_NOT_APPLIED' | 'MISSING_CLIENT_ID' | 'UNAUTHORIZED' | 'IDP_UNREACHABLE' | 'NETWORK_ERROR' | 'BAD_RESPONSE' | (string & {});
+export declare class AgentRegistryError extends Error {
+    readonly code: AgentRegistryErrorCode;
+    /** HTTP status; 0 when no response arrived. */
+    readonly status: number;
+    readonly requestId?: string;
+    readonly details?: unknown;
+    constructor(code: AgentRegistryErrorCode, message: string, status: number, extra?: {
+        requestId?: string;
+        details?: unknown;
+    });
+}
+export interface AgentRegistryClientOptions {
+    /** Absolute origin of the identity service (e.g. IDP_URL). */
+    baseUrl: string;
+    /** A tenant-admin access token (completed MFA), or a function that returns one. */
+    accessToken: string | (() => string | Promise<string>);
+    /** Override for tests; defaults to bearerFetch (global fetch, never follows a redirect). */
+    fetch?: (input: string, init: RequestInit) => Promise<Response>;
+}
+export interface AgentRegistryClient {
+    register(input: RegisterAgentInput): Promise<RegisterAgentResult>;
+    list(): Promise<ListAgentsResult>;
+    get(id: number): Promise<GetAgentResult>;
+}
+export declare function createAgentRegistryClient(options: AgentRegistryClientOptions): AgentRegistryClient;

package/dist/agents/registry.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentRegistryError = exports.AGENT_HOST_CLASSES = void 0;
+exports.createAgentRegistryClient = createAgentRegistryClient;
+/**
+ * REG-002 (Keel Registry): the SDK half of "Registration API and SDK".
+ *
+ * A typed client over the tenant-admin agent door in PayEz-Core:
+ *   PayEz.Apis/PayEz.External.Id.Api/Controllers/ClientAgentsController.cs @ 22d44a34c
+ *     POST api/client/agents       Register  (:332-367)  body { user_name, owner_user_id, host_class } -> 201 { item, created, audited }
+ *     GET  api/client/agents       List      (:92-107)   -> { client_id, demo_token_ready, items, apps }
+ *     GET  api/client/agents/{id}  Get       (:126-133)  -> { item, apps } | 404
+ *   Gate: payez_admin / idp_admin_ui_graft_admin with completed MFA (:39-40). The client comes from the TOKEN, never from the
+ *   body, so this client has no client-id argument and cannot register into another client.
+ *
+ * Contract this client keeps:
+ *   - a refusal is thrown as an AgentRegistryError carrying the server's `code` AS-IS (VALIDATION_ERROR, OWNER_NOT_ELIGIBLE,
+ *     OWNER_NOT_MEMBER, AGENT_NAME_TAKEN, AUDIT_WRITE_FAILED_NOT_APPLIED, MISSING_CLIENT_ID, UNAUTHORIZED, ...). It is never
+ *     re-worded, mapped, or swallowed.
+ *   - NO RETRY, of any status. A 409 AGENT_NAME_TAKEN means the name exists; sending it again can only repeat the answer, and a
+ *     register that timed out may have been applied, so the caller (who can read the list) decides, not this client.
+ *   - no validation of the body before sending: the server's validation is the authority and its code is what the caller gets.
+ *   - the bearer never follows a redirect (bearerFetch) and is never put in an error, a message or a log line.
+ *
+ * A newly registered agent is PENDING until an admin activates it (PAY-2069); its first mint is refused AGENT_PENDING.
+ */
+const bearer_fetch_1 = require("../lib/bearer-fetch");
+const idp_url_guard_1 = require("../lib/idp-url-guard");
+/** Core PayEzEndpoints.AgentTokens.AllowedHostClasses (PayEzEndpoints.cs:187,194,228). The server is the authority; this is for typing only. */
+exports.AGENT_HOST_CLASSES = ['rig_pane', 'contractor'];
+class AgentRegistryError extends Error {
+    code;
+    /** HTTP status; 0 when no response arrived. */
+    status;
+    requestId;
+    details;
+    constructor(code, message, status, extra) {
+        super(message);
+        this.name = 'AgentRegistryError';
+        this.code = code;
+        this.status = status;
+        this.requestId = extra?.requestId;
+        this.details = extra?.details;
+    }
+}
+exports.AgentRegistryError = AgentRegistryError;
+function createAgentRegistryClient(options) {
+    (0, idp_url_guard_1.assertAbsoluteIdpUrl)(options.baseUrl);
+    const base = options.baseUrl.replace(/\/+$/, '');
+    const send = options.fetch ?? ((input, init) => (0, bearer_fetch_1.bearerFetch)(input, init));
+    async function call(path, init) {
+        const token = typeof options.accessToken === 'function' ? await options.accessToken() : options.accessToken;
+        let res;
+        try {
+            res = await send(`${base}${path}`, {
+                method: init.method,
+                headers: {
+                    Accept: 'application/json',
+                    ...(init.body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+                    Authorization: `Bearer ${token}`,
+                },
+                ...(init.body !== undefined ? { body: JSON.stringify(init.body) } : {}),
+                cache: 'no-store',
+            });
+        }
+        catch {
+            // Fixed text: a transport error's own message can carry the URL or headers.
+            // A POST that failed in transit may still have been applied (the server can answer after the client gave up), so for register the text says the
+            // outcome is unknown and to read the list; it is never retried here. A GET changes nothing, so it keeps the plain text.
+            throw new AgentRegistryError('NETWORK_ERROR', init.method === 'POST'
+                ? 'The identity service could not be reached; the outcome is unknown, so read the list before registering again'
+                : 'The identity service could not be reached', 0);
+        }
+        let json = null;
+        try {
+            json = await res.json();
+        }
+        catch {
+            json = null;
+        }
+        if (!res.ok) {
+            const e = json?.error;
+            throw new AgentRegistryError(typeof e?.code === 'string' ? e.code : `HTTP_${res.status}`, typeof e?.message === 'string' ? e.message : `The identity service answered ${res.status}`, res.status, { requestId: json?.request_id ?? e?.support?.request_id, details: e?.details });
+        }
+        const data = json?.data;
+        if (json?.success === false || data == null || typeof data !== 'object') {
+            throw new AgentRegistryError('BAD_RESPONSE', 'The identity service answered without the expected data', res.status);
+        }
+        return data;
+    }
+    return {
+        register: (input) => call('/api/client/agents', {
+            method: 'POST',
+            // Exactly the three fields the door binds; nothing else is forwarded.
+            body: { user_name: input.user_name, owner_user_id: input.owner_user_id, host_class: input.host_class },
+        }),
+        list: () => call('/api/client/agents', { method: 'GET' }),
+        get: (id) => call(`/api/client/agents/${encodeURIComponent(String(id))}`, { method: 'GET' }),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payez/next-mvp",
-  "version": "4.8.3",
+  "version": "4.8.4",
   "sideEffects": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -810,6 +810,11 @@
       "require": "./dist/hooks/useViabilitySession.js",
       "default": "./dist/hooks/useViabilitySession.js"
     },
+    "./agents": {
+      "types": "./dist/agents/index.d.ts",
+      "require": "./dist/agents/index.js",
+      "default": "./dist/agents/index.js"
+    },
     "./vibe": {
       "types": "./dist/vibe/index.d.ts",
       "require": "./dist/vibe/index.js",

package/src/agents/index.ts

@@ -0,0 +1 @@
+export * from './registry';

package/src/agents/registry.ts

@@ -0,0 +1,179 @@
+/**
+ * REG-002 (Keel Registry): the SDK half of "Registration API and SDK".
+ *
+ * A typed client over the tenant-admin agent door in PayEz-Core:
+ *   PayEz.Apis/PayEz.External.Id.Api/Controllers/ClientAgentsController.cs @ 22d44a34c
+ *     POST api/client/agents       Register  (:332-367)  body { user_name, owner_user_id, host_class } -> 201 { item, created, audited }
+ *     GET  api/client/agents       List      (:92-107)   -> { client_id, demo_token_ready, items, apps }
+ *     GET  api/client/agents/{id}  Get       (:126-133)  -> { item, apps } | 404
+ *   Gate: payez_admin / idp_admin_ui_graft_admin with completed MFA (:39-40). The client comes from the TOKEN, never from the
+ *   body, so this client has no client-id argument and cannot register into another client.
+ *
+ * Contract this client keeps:
+ *   - a refusal is thrown as an AgentRegistryError carrying the server's `code` AS-IS (VALIDATION_ERROR, OWNER_NOT_ELIGIBLE,
+ *     OWNER_NOT_MEMBER, AGENT_NAME_TAKEN, AUDIT_WRITE_FAILED_NOT_APPLIED, MISSING_CLIENT_ID, UNAUTHORIZED, ...). It is never
+ *     re-worded, mapped, or swallowed.
+ *   - NO RETRY, of any status. A 409 AGENT_NAME_TAKEN means the name exists; sending it again can only repeat the answer, and a
+ *     register that timed out may have been applied, so the caller (who can read the list) decides, not this client.
+ *   - no validation of the body before sending: the server's validation is the authority and its code is what the caller gets.
+ *   - the bearer never follows a redirect (bearerFetch) and is never put in an error, a message or a log line.
+ *
+ * A newly registered agent is PENDING until an admin activates it (PAY-2069); its first mint is refused AGENT_PENDING.
+ */
+import { bearerFetch } from '../lib/bearer-fetch';
+import { assertAbsoluteIdpUrl } from '../lib/idp-url-guard';
+
+/** Core PayEzEndpoints.AgentTokens.AllowedHostClasses (PayEzEndpoints.cs:187,194,228). The server is the authority; this is for typing only. */
+export const AGENT_HOST_CLASSES = ['rig_pane', 'contractor'] as const;
+export type AgentHostClass = (typeof AGENT_HOST_CLASSES)[number];
+
+export interface RegisterAgentInput {
+  /** 3-64 chars, letters/digits/'.'/'_'/'-', starting with a letter or digit; unique across the IdP. */
+  user_name: string;
+  /** A person (user id) who is an approved, active member of this client. */
+  owner_user_id: number;
+  host_class: AgentHostClass;
+}
+
+export interface AgentRecord {
+  id: number;
+  user_name: string;
+  owner: { kind: 'person'; user_id: number; display_name: string | null; approved: boolean } | null;
+  status: { code: string; reason: string | null };
+  host_class: string | null;
+  agent_profile_id: number | null;
+}
+
+export interface MintableApp {
+  id: number;
+  name: string;
+  allowed_scopes: unknown;
+}
+
+export interface RegisterAgentResult {
+  item: AgentRecord | null;
+  created: boolean;
+  audited: boolean;
+}
+
+export interface ListAgentsResult {
+  client_id: number;
+  demo_token_ready: boolean | null;
+  items: AgentRecord[];
+  apps: MintableApp[];
+}
+
+export interface GetAgentResult {
+  item: AgentRecord;
+  apps: MintableApp[];
+}
+
+/** Codes this door is known to answer. `string` stays in the union: an unknown code is surfaced, not hidden. */
+export type AgentRegistryErrorCode =
+  | 'VALIDATION_ERROR'
+  | 'OWNER_NOT_ELIGIBLE'
+  | 'OWNER_NOT_MEMBER'
+  | 'AGENT_NAME_TAKEN'
+  | 'AUDIT_WRITE_FAILED_NOT_APPLIED'
+  | 'MISSING_CLIENT_ID'
+  | 'UNAUTHORIZED'
+  | 'IDP_UNREACHABLE'
+  | 'NETWORK_ERROR'
+  | 'BAD_RESPONSE'
+  | (string & {});
+
+export class AgentRegistryError extends Error {
+  readonly code: AgentRegistryErrorCode;
+  /** HTTP status; 0 when no response arrived. */
+  readonly status: number;
+  readonly requestId?: string;
+  readonly details?: unknown;
+
+  constructor(code: AgentRegistryErrorCode, message: string, status: number, extra?: { requestId?: string; details?: unknown }) {
+    super(message);
+    this.name = 'AgentRegistryError';
+    this.code = code;
+    this.status = status;
+    this.requestId = extra?.requestId;
+    this.details = extra?.details;
+  }
+}
+
+export interface AgentRegistryClientOptions {
+  /** Absolute origin of the identity service (e.g. IDP_URL). */
+  baseUrl: string;
+  /** A tenant-admin access token (completed MFA), or a function that returns one. */
+  accessToken: string | (() => string | Promise<string>);
+  /** Override for tests; defaults to bearerFetch (global fetch, never follows a redirect). */
+  fetch?: (input: string, init: RequestInit) => Promise<Response>;
+}
+
+export interface AgentRegistryClient {
+  register(input: RegisterAgentInput): Promise<RegisterAgentResult>;
+  list(): Promise<ListAgentsResult>;
+  get(id: number): Promise<GetAgentResult>;
+}
+
+export function createAgentRegistryClient(options: AgentRegistryClientOptions): AgentRegistryClient {
+  assertAbsoluteIdpUrl(options.baseUrl);
+  const base = options.baseUrl.replace(/\/+$/, '');
+  const send = options.fetch ?? ((input: string, init: RequestInit) => bearerFetch(input, init));
+
+  async function call<T>(path: string, init: { method: 'GET' | 'POST'; body?: unknown }): Promise<T> {
+    const token = typeof options.accessToken === 'function' ? await options.accessToken() : options.accessToken;
+    let res: Response;
+    try {
+      res = await send(`${base}${path}`, {
+        method: init.method,
+        headers: {
+          Accept: 'application/json',
+          ...(init.body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+          Authorization: `Bearer ${token}`,
+        },
+        ...(init.body !== undefined ? { body: JSON.stringify(init.body) } : {}),
+        cache: 'no-store',
+      });
+    } catch {
+      // Fixed text: a transport error's own message can carry the URL or headers.
+      // A POST that failed in transit may still have been applied (the server can answer after the client gave up), so for register the text says the
+      // outcome is unknown and to read the list; it is never retried here. A GET changes nothing, so it keeps the plain text.
+      throw new AgentRegistryError(
+        'NETWORK_ERROR',
+        init.method === 'POST'
+          ? 'The identity service could not be reached; the outcome is unknown, so read the list before registering again'
+          : 'The identity service could not be reached',
+        0,
+      );
+    }
+
+    let json: any = null;
+    try { json = await res.json(); } catch { json = null; }
+
+    if (!res.ok) {
+      const e = json?.error;
+      throw new AgentRegistryError(
+        typeof e?.code === 'string' ? e.code : `HTTP_${res.status}`,
+        typeof e?.message === 'string' ? e.message : `The identity service answered ${res.status}`,
+        res.status,
+        { requestId: json?.request_id ?? e?.support?.request_id, details: e?.details },
+      );
+    }
+
+    const data = json?.data;
+    if (json?.success === false || data == null || typeof data !== 'object') {
+      throw new AgentRegistryError('BAD_RESPONSE', 'The identity service answered without the expected data', res.status);
+    }
+    return data as T;
+  }
+
+  return {
+    register: (input) =>
+      call<RegisterAgentResult>('/api/client/agents', {
+        method: 'POST',
+        // Exactly the three fields the door binds; nothing else is forwarded.
+        body: { user_name: input.user_name, owner_user_id: input.owner_user_id, host_class: input.host_class },
+      }),
+    list: () => call<ListAgentsResult>('/api/client/agents', { method: 'GET' }),
+    get: (id) => call<GetAgentResult>(`/api/client/agents/${encodeURIComponent(String(id))}`, { method: 'GET' }),
+  };
+}