@topolo/sdk 0.2.12 → 0.3.0

package/dist/index.cjs

@@ -1925,7 +1925,9 @@ function resolveServiceUrl(service, overrides) {
 
 // src/client.ts
 var WRITE_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
-var TopoloClient = class {
+var POSITIVE_CACHE_TTL_MS = 5 * 60 * 1e3;
+var NEGATIVE_CACHE_TTL_MS = 60 * 1e3;
+var TopoloClient = class _TopoloClient {
   credential;
   agent;
   serviceUrls;
@@ -1933,6 +1935,20 @@ var TopoloClient = class {
   timeoutMs;
   fetchImpl;
   debug;
+  /**
+   * Process-wide cache for slug → service-id lookups. Keyed by
+   * `${authBaseUrl}|${slug}` so multiple `TopoloClient` instances pointing at
+   * the same Auth share, but staging vs prod don't poison each other.
+   * Cleared via `TopoloClient.clearServiceIdCache()` if a test needs it.
+   */
+  static serviceIdCache = /* @__PURE__ */ new Map();
+  /**
+   * Drop the slug→service-id cache. Test-only — production callers should
+   * let the 5-minute TTL expire naturally.
+   */
+  static clearServiceIdCache() {
+    _TopoloClient.serviceIdCache.clear();
+  }
   constructor(options) {
     if (!options.credential) throw new TopoloAuthError("credential is required");
     if (!options.agent?.clientName) throw new TopoloAuthError("agent.clientName is required");
@@ -2047,6 +2063,66 @@ var TopoloClient = class {
     });
     return parsed;
   }
+  /**
+   * Resolve a service-slug → opaque service-id via TopoloAuth.
+   *
+   * Replaces the SDK-baked `PLATFORM_SERVICE_IDS` map (deprecated in 0.3.0,
+   * removed in 0.4.0). Slug shape accepted: either the canonical Auth slug
+   * (e.g. `topolo-notify`) or the SDK short id (`notify`) — Auth's resolver
+   * understands both.
+   *
+   * Cache: 5 minutes per process per `(slug, auth_base_url)`. Negative
+   * results (404) are cached for 60s so a typo doesn't hot-loop the
+   * resolver. Returns null when the slug isn't registered — callers decide
+   * whether to throw.
+   *
+   * No credential is sent: the endpoint is public (slugs aren't secret).
+   * This keeps the resolver usable during early bootstrap before a caller
+   * has acquired an access token.
+   */
+  async getServiceIdBySlug(slug) {
+    if (typeof slug !== "string") return null;
+    const normalized = slug.trim().toLowerCase();
+    if (!normalized) return null;
+    const authBase = resolveServiceUrl("auth", this.serviceUrls);
+    const cacheKey = `${authBase}|${normalized}`;
+    const now = Date.now();
+    const cached = _TopoloClient.serviceIdCache.get(cacheKey);
+    if (cached && cached.expiresAt > now) {
+      return cached.value;
+    }
+    const url = new URL(
+      `/api/services/by-slug/${encodeURIComponent(normalized)}`,
+      authBase.endsWith("/") ? authBase : `${authBase}/`
+    ).toString();
+    let res;
+    try {
+      res = await this.fetchImpl(url, {
+        method: "GET",
+        headers: { Accept: "application/json" }
+      });
+    } catch {
+      return null;
+    }
+    if (res.status === 404) {
+      _TopoloClient.serviceIdCache.set(cacheKey, {
+        value: null,
+        expiresAt: now + NEGATIVE_CACHE_TTL_MS
+      });
+      return null;
+    }
+    if (!res.ok) {
+      return null;
+    }
+    const body = await res.json().catch(() => null);
+    const serviceId = body?.data?.service_id;
+    const value = typeof serviceId === "string" && serviceId ? serviceId : null;
+    _TopoloClient.serviceIdCache.set(cacheKey, {
+      value,
+      expiresAt: now + POSITIVE_CACHE_TTL_MS
+    });
+    return value;
+  }
   /**
    * Introspect the current credential. Returns the caller's resolved identity,
    * organization, and permission set. Used by CLI `whoami` and by MCP to gate

package/dist/index.d.cts

@@ -78,6 +78,14 @@ declare const SERVICES: {
     readonly web: "https://web-api.topolo.app";
 };
 type ServiceId = keyof typeof SERVICES;
+/**
+ * @deprecated since 0.3.0 — opaque service ids are no longer baked into the
+ * SDK. Use `TopoloClient.getServiceIdBySlug(slug)` which hits
+ * `GET /api/services/by-slug/:slug` on TopoloAuth at runtime. This map is
+ * still populated as a build-time snapshot for backward compatibility and
+ * will be removed in 0.4.0. Stale entries are expected — do not rely on
+ * presence/absence for catalog membership.
+ */
 declare const PLATFORM_SERVICE_IDS: Partial<Record<ServiceId, string>>;
 
 declare const APPLICATIONS: {
@@ -1254,6 +1262,18 @@ declare class TopoloClient {
     private readonly timeoutMs;
     private readonly fetchImpl;
     private readonly debug?;
+    /**
+     * Process-wide cache for slug → service-id lookups. Keyed by
+     * `${authBaseUrl}|${slug}` so multiple `TopoloClient` instances pointing at
+     * the same Auth share, but staging vs prod don't poison each other.
+     * Cleared via `TopoloClient.clearServiceIdCache()` if a test needs it.
+     */
+    private static readonly serviceIdCache;
+    /**
+     * Drop the slug→service-id cache. Test-only — production callers should
+     * let the 5-minute TTL expire naturally.
+     */
+    static clearServiceIdCache(): void;
     constructor(options: TopoloClientOptions);
     private emit;
     /**
@@ -1262,6 +1282,24 @@ declare class TopoloClient {
      * use and for the generic `topolo api` / MCP passthrough tool.
      */
     request<T = unknown>(opts: RequestOptions): Promise<T>;
+    /**
+     * Resolve a service-slug → opaque service-id via TopoloAuth.
+     *
+     * Replaces the SDK-baked `PLATFORM_SERVICE_IDS` map (deprecated in 0.3.0,
+     * removed in 0.4.0). Slug shape accepted: either the canonical Auth slug
+     * (e.g. `topolo-notify`) or the SDK short id (`notify`) — Auth's resolver
+     * understands both.
+     *
+     * Cache: 5 minutes per process per `(slug, auth_base_url)`. Negative
+     * results (404) are cached for 60s so a typo doesn't hot-loop the
+     * resolver. Returns null when the slug isn't registered — callers decide
+     * whether to throw.
+     *
+     * No credential is sent: the endpoint is public (slugs aren't secret).
+     * This keeps the resolver usable during early bootstrap before a caller
+     * has acquired an access token.
+     */
+    getServiceIdBySlug(slug: string): Promise<string | null>;
     /**
      * Introspect the current credential. Returns the caller's resolved identity,
      * organization, and permission set. Used by CLI `whoami` and by MCP to gate

package/dist/index.d.ts

@@ -78,6 +78,14 @@ declare const SERVICES: {
     readonly web: "https://web-api.topolo.app";
 };
 type ServiceId = keyof typeof SERVICES;
+/**
+ * @deprecated since 0.3.0 — opaque service ids are no longer baked into the
+ * SDK. Use `TopoloClient.getServiceIdBySlug(slug)` which hits
+ * `GET /api/services/by-slug/:slug` on TopoloAuth at runtime. This map is
+ * still populated as a build-time snapshot for backward compatibility and
+ * will be removed in 0.4.0. Stale entries are expected — do not rely on
+ * presence/absence for catalog membership.
+ */
 declare const PLATFORM_SERVICE_IDS: Partial<Record<ServiceId, string>>;
 
 declare const APPLICATIONS: {
@@ -1254,6 +1262,18 @@ declare class TopoloClient {
     private readonly timeoutMs;
     private readonly fetchImpl;
     private readonly debug?;
+    /**
+     * Process-wide cache for slug → service-id lookups. Keyed by
+     * `${authBaseUrl}|${slug}` so multiple `TopoloClient` instances pointing at
+     * the same Auth share, but staging vs prod don't poison each other.
+     * Cleared via `TopoloClient.clearServiceIdCache()` if a test needs it.
+     */
+    private static readonly serviceIdCache;
+    /**
+     * Drop the slug→service-id cache. Test-only — production callers should
+     * let the 5-minute TTL expire naturally.
+     */
+    static clearServiceIdCache(): void;
     constructor(options: TopoloClientOptions);
     private emit;
     /**
@@ -1262,6 +1282,24 @@ declare class TopoloClient {
      * use and for the generic `topolo api` / MCP passthrough tool.
      */
     request<T = unknown>(opts: RequestOptions): Promise<T>;
+    /**
+     * Resolve a service-slug → opaque service-id via TopoloAuth.
+     *
+     * Replaces the SDK-baked `PLATFORM_SERVICE_IDS` map (deprecated in 0.3.0,
+     * removed in 0.4.0). Slug shape accepted: either the canonical Auth slug
+     * (e.g. `topolo-notify`) or the SDK short id (`notify`) — Auth's resolver
+     * understands both.
+     *
+     * Cache: 5 minutes per process per `(slug, auth_base_url)`. Negative
+     * results (404) are cached for 60s so a typo doesn't hot-loop the
+     * resolver. Returns null when the slug isn't registered — callers decide
+     * whether to throw.
+     *
+     * No credential is sent: the endpoint is public (slugs aren't secret).
+     * This keeps the resolver usable during early bootstrap before a caller
+     * has acquired an access token.
+     */
+    getServiceIdBySlug(slug: string): Promise<string | null>;
     /**
      * Introspect the current credential. Returns the caller's resolved identity,
      * organization, and permission set. Used by CLI `whoami` and by MCP to gate

package/dist/index.js

@@ -1870,7 +1870,9 @@ function resolveServiceUrl(service, overrides) {
 
 // src/client.ts
 var WRITE_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
-var TopoloClient = class {
+var POSITIVE_CACHE_TTL_MS = 5 * 60 * 1e3;
+var NEGATIVE_CACHE_TTL_MS = 60 * 1e3;
+var TopoloClient = class _TopoloClient {
   credential;
   agent;
   serviceUrls;
@@ -1878,6 +1880,20 @@ var TopoloClient = class {
   timeoutMs;
   fetchImpl;
   debug;
+  /**
+   * Process-wide cache for slug → service-id lookups. Keyed by
+   * `${authBaseUrl}|${slug}` so multiple `TopoloClient` instances pointing at
+   * the same Auth share, but staging vs prod don't poison each other.
+   * Cleared via `TopoloClient.clearServiceIdCache()` if a test needs it.
+   */
+  static serviceIdCache = /* @__PURE__ */ new Map();
+  /**
+   * Drop the slug→service-id cache. Test-only — production callers should
+   * let the 5-minute TTL expire naturally.
+   */
+  static clearServiceIdCache() {
+    _TopoloClient.serviceIdCache.clear();
+  }
   constructor(options) {
     if (!options.credential) throw new TopoloAuthError("credential is required");
     if (!options.agent?.clientName) throw new TopoloAuthError("agent.clientName is required");
@@ -1992,6 +2008,66 @@ var TopoloClient = class {
     });
     return parsed;
   }
+  /**
+   * Resolve a service-slug → opaque service-id via TopoloAuth.
+   *
+   * Replaces the SDK-baked `PLATFORM_SERVICE_IDS` map (deprecated in 0.3.0,
+   * removed in 0.4.0). Slug shape accepted: either the canonical Auth slug
+   * (e.g. `topolo-notify`) or the SDK short id (`notify`) — Auth's resolver
+   * understands both.
+   *
+   * Cache: 5 minutes per process per `(slug, auth_base_url)`. Negative
+   * results (404) are cached for 60s so a typo doesn't hot-loop the
+   * resolver. Returns null when the slug isn't registered — callers decide
+   * whether to throw.
+   *
+   * No credential is sent: the endpoint is public (slugs aren't secret).
+   * This keeps the resolver usable during early bootstrap before a caller
+   * has acquired an access token.
+   */
+  async getServiceIdBySlug(slug) {
+    if (typeof slug !== "string") return null;
+    const normalized = slug.trim().toLowerCase();
+    if (!normalized) return null;
+    const authBase = resolveServiceUrl("auth", this.serviceUrls);
+    const cacheKey = `${authBase}|${normalized}`;
+    const now = Date.now();
+    const cached = _TopoloClient.serviceIdCache.get(cacheKey);
+    if (cached && cached.expiresAt > now) {
+      return cached.value;
+    }
+    const url = new URL(
+      `/api/services/by-slug/${encodeURIComponent(normalized)}`,
+      authBase.endsWith("/") ? authBase : `${authBase}/`
+    ).toString();
+    let res;
+    try {
+      res = await this.fetchImpl(url, {
+        method: "GET",
+        headers: { Accept: "application/json" }
+      });
+    } catch {
+      return null;
+    }
+    if (res.status === 404) {
+      _TopoloClient.serviceIdCache.set(cacheKey, {
+        value: null,
+        expiresAt: now + NEGATIVE_CACHE_TTL_MS
+      });
+      return null;
+    }
+    if (!res.ok) {
+      return null;
+    }
+    const body = await res.json().catch(() => null);
+    const serviceId = body?.data?.service_id;
+    const value = typeof serviceId === "string" && serviceId ? serviceId : null;
+    _TopoloClient.serviceIdCache.set(cacheKey, {
+      value,
+      expiresAt: now + POSITIVE_CACHE_TTL_MS
+    });
+    return value;
+  }
   /**
    * Introspect the current credential. Returns the caller's resolved identity,
    * organization, and permission set. Used by CLI `whoami` and by MCP to gate

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topolo/sdk",
-  "version": "0.2.12",
+  "version": "0.3.0",
   "description": "Typed client SDK for the Topolo platform. Used by TopoloCli, TopoloMCP, and third-party agents.",
   "type": "module",
   "main": "./dist/index.js",

package/src/client.test.ts

@@ -251,5 +251,82 @@ describe('TopoloClient.debug hook', () => {
   });
 });
 
+describe('TopoloClient.getServiceIdBySlug', () => {
+  function freshClient(impl: typeof fetch, serviceUrls?: Record<string, string>) {
+    TopoloClient.clearServiceIdCache();
+    return new TopoloClient({
+      credential: { kind: 'api_key', apiKey: 'x' },
+      agent: AGENT,
+      fetch: impl,
+      serviceUrls: serviceUrls as never,
+    });
+  }
+
+  it('resolves a known slug via /api/services/by-slug/:slug', async () => {
+    const { impl, calls } = stubFetch([
+      { body: { success: true, data: { service_id: 'srv_abc123', base_url: 'https://x' } } },
+    ]);
+    const client = freshClient(impl, { auth: 'https://auth.example.com' });
+    const id = await client.getServiceIdBySlug('topolo-notify');
+    expect(id).toBe('srv_abc123');
+    expect(calls[0]!.url).toBe('https://auth.example.com/api/services/by-slug/topolo-notify');
+    // No auth header — endpoint is public.
+    const headers = new Headers(calls[0]!.init.headers);
+    expect(headers.get('Authorization')).toBeNull();
+    expect(headers.get('X-Api-Key')).toBeNull();
+  });
+
+  it('returns null on 404 and caches the negative result', async () => {
+    const { impl, calls } = stubFetch([{ status: 404, body: { success: false } }]);
+    const client = freshClient(impl, { auth: 'https://auth.example.com' });
+    expect(await client.getServiceIdBySlug('nope')).toBeNull();
+    expect(await client.getServiceIdBySlug('nope')).toBeNull();
+    expect(calls.length).toBe(1);
+  });
+
+  it('caches positive results across calls', async () => {
+    const { impl, calls } = stubFetch([
+      { body: { success: true, data: { service_id: 'srv_iCwM4jGXcwlj' } } },
+    ]);
+    const client = freshClient(impl, { auth: 'https://auth.example.com' });
+    expect(await client.getServiceIdBySlug('topolo-crm')).toBe('srv_iCwM4jGXcwlj');
+    expect(await client.getServiceIdBySlug('topolo-crm')).toBe('srv_iCwM4jGXcwlj');
+    expect(calls.length).toBe(1);
+  });
+
+  it('normalizes slug case + whitespace before hitting the network', async () => {
+    const { impl, calls } = stubFetch([
+      { body: { success: true, data: { service_id: 'srv_x' } } },
+    ]);
+    const client = freshClient(impl, { auth: 'https://auth.example.com' });
+    await client.getServiceIdBySlug('  TOPOLO-NOTIFY  ');
+    expect(calls[0]!.url).toBe('https://auth.example.com/api/services/by-slug/topolo-notify');
+  });
+
+  it('returns null on network failure without poisoning cache', async () => {
+    let throws = true;
+    const impl = vi.fn(async (url: string) => {
+      if (throws) {
+        throws = false;
+        throw new Error('ECONNREFUSED');
+      }
+      return new Response(JSON.stringify({ success: true, data: { service_id: 'srv_y' } }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }) as unknown as typeof fetch;
+    TopoloClient.clearServiceIdCache();
+    const client = new TopoloClient({
+      credential: { kind: 'api_key', apiKey: 'x' },
+      agent: AGENT,
+      fetch: impl,
+      serviceUrls: { auth: 'https://auth.example.com' } as never,
+    });
+    expect(await client.getServiceIdBySlug('flaky')).toBeNull();
+    // Second call retries — earlier null was not cached.
+    expect(await client.getServiceIdBySlug('flaky')).toBe('srv_y');
+  });
+});
+
 // Silence unused-import warning if the bundler later tree-shakes these
 void TopoloHttpError;

package/src/client.ts

@@ -81,6 +81,14 @@ export interface RequestOptions {
 
 const WRITE_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
 
+const POSITIVE_CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+const NEGATIVE_CACHE_TTL_MS = 60 * 1000; // 1 minute
+
+interface ServiceIdCacheEntry {
+  value: string | null;
+  expiresAt: number;
+}
+
 export class TopoloClient {
   private readonly credential: TopoloCredential;
   private readonly agent: AgentIdentity;
@@ -90,6 +98,22 @@ export class TopoloClient {
   private readonly fetchImpl: typeof fetch;
   private readonly debug?: (event: TopoloDebugEvent) => void;
 
+  /**
+   * Process-wide cache for slug → service-id lookups. Keyed by
+   * `${authBaseUrl}|${slug}` so multiple `TopoloClient` instances pointing at
+   * the same Auth share, but staging vs prod don't poison each other.
+   * Cleared via `TopoloClient.clearServiceIdCache()` if a test needs it.
+   */
+  private static readonly serviceIdCache = new Map<string, ServiceIdCacheEntry>();
+
+  /**
+   * Drop the slug→service-id cache. Test-only — production callers should
+   * let the 5-minute TTL expire naturally.
+   */
+  static clearServiceIdCache(): void {
+    TopoloClient.serviceIdCache.clear();
+  }
+
   constructor(options: TopoloClientOptions) {
     if (!options.credential) throw new TopoloAuthError('credential is required');
     if (!options.agent?.clientName) throw new TopoloAuthError('agent.clientName is required');
@@ -224,6 +248,76 @@ export class TopoloClient {
     return parsed as T;
   }
 
+  /**
+   * Resolve a service-slug → opaque service-id via TopoloAuth.
+   *
+   * Replaces the SDK-baked `PLATFORM_SERVICE_IDS` map (deprecated in 0.3.0,
+   * removed in 0.4.0). Slug shape accepted: either the canonical Auth slug
+   * (e.g. `topolo-notify`) or the SDK short id (`notify`) — Auth's resolver
+   * understands both.
+   *
+   * Cache: 5 minutes per process per `(slug, auth_base_url)`. Negative
+   * results (404) are cached for 60s so a typo doesn't hot-loop the
+   * resolver. Returns null when the slug isn't registered — callers decide
+   * whether to throw.
+   *
+   * No credential is sent: the endpoint is public (slugs aren't secret).
+   * This keeps the resolver usable during early bootstrap before a caller
+   * has acquired an access token.
+   */
+  async getServiceIdBySlug(slug: string): Promise<string | null> {
+    if (typeof slug !== 'string') return null;
+    const normalized = slug.trim().toLowerCase();
+    if (!normalized) return null;
+
+    const authBase = resolveServiceUrl('auth', this.serviceUrls);
+    const cacheKey = `${authBase}|${normalized}`;
+    const now = Date.now();
+    const cached = TopoloClient.serviceIdCache.get(cacheKey);
+    if (cached && cached.expiresAt > now) {
+      return cached.value;
+    }
+
+    const url = new URL(
+      `/api/services/by-slug/${encodeURIComponent(normalized)}`,
+      authBase.endsWith('/') ? authBase : `${authBase}/`,
+    ).toString();
+
+    let res: Response;
+    try {
+      res = await this.fetchImpl(url, {
+        method: 'GET',
+        headers: { Accept: 'application/json' },
+      });
+    } catch {
+      // Network-level failure — don't poison cache; let the caller retry.
+      return null;
+    }
+
+    if (res.status === 404) {
+      TopoloClient.serviceIdCache.set(cacheKey, {
+        value: null,
+        expiresAt: now + NEGATIVE_CACHE_TTL_MS,
+      });
+      return null;
+    }
+
+    if (!res.ok) {
+      return null;
+    }
+
+    const body = (await res.json().catch(() => null)) as
+      | { success?: boolean; data?: { service_id?: unknown } }
+      | null;
+    const serviceId = body?.data?.service_id;
+    const value = typeof serviceId === 'string' && serviceId ? serviceId : null;
+    TopoloClient.serviceIdCache.set(cacheKey, {
+      value,
+      expiresAt: now + POSITIVE_CACHE_TTL_MS,
+    });
+    return value;
+  }
+
   /**
    * Introspect the current credential. Returns the caller's resolved identity,
    * organization, and permission set. Used by CLI `whoami` and by MCP to gate

package/src/services.generated.ts

@@ -51,6 +51,14 @@ export const SERVICES = {
 
 export type ServiceId = keyof typeof SERVICES;
 
+/**
+ * @deprecated since 0.3.0 — opaque service ids are no longer baked into the
+ * SDK. Use `TopoloClient.getServiceIdBySlug(slug)` which hits
+ * `GET /api/services/by-slug/:slug` on TopoloAuth at runtime. This map is
+ * still populated as a build-time snapshot for backward compatibility and
+ * will be removed in 0.4.0. Stale entries are expected — do not rely on
+ * presence/absence for catalog membership.
+ */
 export const PLATFORM_SERVICE_IDS: Partial<Record<ServiceId, string>> = {
   books: "srv_0g260hbN8oqv",
   bugfix: "srv_kQ1t8qUSDgNs",

package/src/services.test.ts

@@ -84,11 +84,20 @@ describe('service registry', () => {
     expect(DEFAULT_SERVICE_URLS).not.toHaveProperty('web.runtime');
   });
 
-  it('infers platform Auth service ids from scaffolded app metadata', async () => {
+  it('still ships PLATFORM_SERVICE_IDS as a deprecated build-time snapshot', async () => {
+    // Deprecated in 0.3.0, removed in 0.4.0. Source of truth has moved to
+    // TopoloAuth's GET /api/services/by-slug/:slug — see
+    // TopoloClient.getServiceIdBySlug. We only sanity-check that the snapshot
+    // is non-empty and that the values look like opaque service ids; specific
+    // ids are no longer load-bearing.
     const { PLATFORM_SERVICE_IDS } = await import('./services.js');
 
-    expect(PLATFORM_SERVICE_IDS.books).toBe('srv_topolo_books');
-    expect(PLATFORM_SERVICE_IDS.customer_success).toBe('srv_topolo_success');
+    const entries = Object.entries(PLATFORM_SERVICE_IDS);
+    expect(entries.length).toBeGreaterThan(0);
+    for (const [, id] of entries) {
+      expect(typeof id).toBe('string');
+      expect(id).toMatch(/^srv_/);
+    }
   });
 
   it('maps every callable service back to an application catalog entry', () => {