feat(api): give the admin app its own generated client and mark the CRM operations x-internal (#1286)

Synced from sferarc/pgbeam@4c9525c

Author: SferaDev

src/client.ts

@@ -1,17 +1,45 @@
-import {
-  type ApiOperations,
-  operationsByPath,
-  operationsByTag,
-  type RequestMap,
-  type Route,
-} from "./generated/operations-map.gen";
+import { type ApiClient, operationsByPath, operationsByTag } from "./generated/operations-map.gen";
 import {
   type FetcherOptions,
   fetcher,
   type OnResponseHook,
   type RetryConfig,
 } from "./utils/fetcher";
 
+export type { ApiClient };
+
+/** A single operation's HTTP method and path template. */
+export interface OperationMeta {
+  method: string;
+  path: string;
+}
+
+/**
+ * The dispatch tables the client drives: operations grouped by tag (for
+ * `api.<tag>.<operationId>()`) and keyed by route (for `api.request()`).
+ *
+ * Defaults to the registry generated from the public API bundle. A client
+ * generated from a different bundle passes its own registry and its own `api`
+ * type, so it reuses this transport (auth, retries, error mapping) instead of
+ * forking it. See `@pgbeam/sdk-internal`.
+ */
+export interface OperationRegistry {
+  byTag: Record<string, Record<string, OperationMeta>>;
+  byPath: Record<string, OperationMeta>;
+}
+
+const publicRegistry: OperationRegistry = {
+  byTag: operationsByTag,
+  byPath: operationsByPath,
+};
+
+/** Params accepted by every generated operation, before the surface types narrow them. */
+interface CallParams {
+  pathParams?: FetcherOptions["pathParams"];
+  queryParams?: FetcherOptions["queryParams"];
+  body?: unknown;
+}
+
 export interface PgBeamClientOptions {
   /** JWT token, or async function that resolves one (for lazy/refreshing tokens). */
   token: string | null | (() => Promise<string | null>);
@@ -23,32 +51,18 @@ export interface PgBeamClientOptions {
   onResponse?: OnResponseHook;
   /** Retry configuration. Default: { maxRetries: 5 }. Set false to disable. */
   retry?: RetryConfig | false;
+  /** Operation registry to dispatch on. Defaults to the public API's. */
+  operations?: OperationRegistry;
 }
 
-/** Type-safe client with tag-based proxy access and .request() method. */
-export type ApiClient = ApiOperations & {
-  /**
-   * Type-safe request by route string.
-   *
-   * @example
-   * const projects = await api.request('GET /v1/projects', { queryParams: { org_id } });
-   * const project = await api.request('GET /v1/projects/{project_id}', { pathParams: { project_id } });
-   */
-  request: <K extends Route>(
-    route: K,
-    ...args: RequestMap[K]["params"] extends undefined
-      ? [params?: undefined]
-      : [params: RequestMap[K]["params"]]
-  ) => Promise<RequestMap[K]["response"]>;
-};
-
-export class PgBeamClient {
+export class PgBeamClient<TApi = ApiClient> {
   private _baseUrl: string;
   private _tokenOrFn: string | null | (() => Promise<string | null>);
   private _fetchImpl?: typeof globalThis.fetch;
   private _onResponse?: OnResponseHook;
   private _retry?: RetryConfig;
-  private _api?: ApiClient;
+  private _operations: OperationRegistry;
+  private _api?: TApi;
 
   constructor(options: PgBeamClientOptions) {
     this._baseUrl = options.baseUrl;
@@ -57,6 +71,7 @@ export class PgBeamClient {
     this._onResponse = options.onResponse;
     this._retry =
       options.retry === false ? { maxRetries: 0 } : (options.retry ?? { maxRetries: 5 });
+    this._operations = options.operations ?? publicRegistry;
   }
 
   private async _resolveToken(): Promise<string | null> {
@@ -66,71 +81,57 @@ export class PgBeamClient {
     return this._tokenOrFn;
   }
 
-  private _call(method: string, path: string) {
-    return async (params: Record<string, unknown> = {}) => {
-      const token = await this._resolveToken();
-      return fetcher({
-        method,
-        path,
-        pathParams: params.pathParams as FetcherOptions["pathParams"],
-        queryParams: params.queryParams as FetcherOptions["queryParams"],
-        body: params.body,
-        baseUrl: this._baseUrl,
-        token,
-        fetchImpl: this._fetchImpl,
-        onResponse: this._onResponse,
-        retry: this._retry,
-      });
-    };
+  private async _send(meta: OperationMeta, params: CallParams): Promise<unknown> {
+    const token = await this._resolveToken();
+    return fetcher({
+      method: meta.method,
+      path: meta.path,
+      pathParams: params.pathParams,
+      queryParams: params.queryParams,
+      body: params.body,
+      baseUrl: this._baseUrl,
+      token,
+      fetchImpl: this._fetchImpl,
+      onResponse: this._onResponse,
+      retry: this._retry,
+    });
+  }
+
+  private _call(meta: OperationMeta) {
+    return (params: CallParams = {}) => this._send(meta, params);
   }
 
   /** Access API operations via tag-based namespaces or `.request()`. */
-  get api(): ApiClient {
+  get api(): TApi {
     if (this._api) return this._api;
 
-    const request = async <K extends Route>(
-      route: K,
-      params?: RequestMap[K]["params"],
-    ): Promise<RequestMap[K]["response"]> => {
-      const meta = operationsByPath[route as keyof typeof operationsByPath];
-      if (!meta) throw new Error(`Unknown route: ${String(route)}`);
-      const token = await this._resolveToken();
-      return fetcher({
-        method: meta.method,
-        path: meta.path,
-        pathParams: (params as Record<string, unknown> | undefined)
-          ?.pathParams as FetcherOptions["pathParams"],
-        queryParams: (params as Record<string, unknown> | undefined)
-          ?.queryParams as FetcherOptions["queryParams"],
-        body: (params as Record<string, unknown> | undefined)?.body,
-        baseUrl: this._baseUrl,
-        token,
-        fetchImpl: this._fetchImpl,
-        onResponse: this._onResponse,
-        retry: this._retry,
-      });
+    // Async so an unknown route rejects rather than throwing synchronously,
+    // which is what callers awaiting .request() expect.
+    const request = async (route: string, params: CallParams = {}) => {
+      const meta = this._operations.byPath[route];
+      if (!meta) throw new Error(`Unknown route: ${route}`);
+      return this._send(meta, params);
     };
 
-    this._api = new Proxy({} as ApiClient, {
+    this._api = new Proxy({} as TApi, {
       get: (_, prop: string) => {
         if (prop === "request") return request;
 
-        const tagOps = operationsByTag[prop as keyof typeof operationsByTag];
+        const tagOps = this._operations.byTag[prop];
         if (!tagOps) return undefined;
 
         return new Proxy(
           {},
           {
             get: (_, method: string) => {
-              const ops = tagOps as Record<string, { method: string; path: string }>;
-              const opMeta = ops[method];
+              const opMeta = tagOps[method];
               if (!opMeta) return undefined;
-              return this._call(opMeta.method, opMeta.path);
+              return this._call(opMeta);
             },
           },
         );
       },
-    }) as ApiClient;
+    }) as TApi;
 
     return this._api;
   }