@joeybuilt/plexo-sdk 0.1.0

package/dist/connect/index.d.ts

@@ -0,0 +1,246 @@
+interface AppToolConfig {
+    description: string;
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+}
+interface AppChannelConfig {
+    description: string;
+    transport?: 'api' | 'webhook' | 'poll';
+    direction?: 'inbound' | 'outbound' | 'bidirectional';
+}
+interface AppConnectorConfig {
+    description: string;
+    scopes?: string[];
+}
+/** Lightweight extension declaration an app registers with Plexo Core. */
+type AppExtension = {
+    id: string;
+    type: 'tool';
+    name: string;
+    config: AppToolConfig;
+} | {
+    id: string;
+    type: 'channel';
+    name: string;
+    config: AppChannelConfig;
+} | {
+    id: string;
+    type: 'connector';
+    name: string;
+    config: AppConnectorConfig;
+};
+interface ResilienceOptions {
+    /** Per-call timeout in ms. Default: 15_000. */
+    timeoutMs?: number;
+    /** Retry backoff schedule for registration. Default: [5_000, 15_000, 45_000]. */
+    registrationBackoffMs?: number[];
+}
+interface PlexoClientOptions {
+    /** Unique app identifier. Must match PLEXO_APP_ID (or APP_ID) in env. */
+    appId: string;
+    /** Plexo Core base URL. e.g. https://plexo.example.com */
+    plexoUrl: string;
+    /** Shared service key — must match PLEXO_SERVICE_KEY on Plexo Core. */
+    serviceKey: string;
+    /** Human-readable app name shown in Plexo UI. Defaults to appId. */
+    displayName?: string;
+    /** Tools, channels, and connectors this app exposes to Plexo agents. */
+    extensions?: AppExtension[];
+    /** Event topics this app may emit. e.g. ['my-app.order.created'] */
+    eventContracts?: string[];
+    resilience?: ResilienceOptions;
+    /** Override fetch for testing or custom retry logic. */
+    fetchImpl?: typeof fetch;
+}
+interface PlexoConnection {
+    id: string;
+    registryId: string;
+    name: string;
+    status: 'active' | 'disconnected' | 'error' | 'expired';
+    scopesGranted: string[] | null;
+    lastVerifiedAt: string | null;
+    createdAt: string;
+}
+interface PlexoToken {
+    access_token: string | null;
+    refresh_token: string | null;
+    expires_at: string | null;
+    email: string | null;
+    scope: string | null;
+}
+interface AiMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+interface AiCompleteOptions {
+    messages: AiMessage[];
+    systemPrompt?: string;
+    maxTokens?: number;
+    taskType?: string;
+}
+interface ChatOptions {
+    message: string;
+    sessionId?: string;
+    sessionContext?: {
+        activeView?: {
+            type: string;
+            id: string;
+            summary: string;
+        };
+        appState?: Record<string, unknown>;
+    };
+}
+interface ChatReply {
+    reply: string;
+    conversationId?: string;
+    sessionId?: string;
+    taskId?: string;
+}
+interface DispatchOptions {
+    channel: 'email' | 'push' | 'sms' | 'telegram' | string;
+    recipientUserId: string;
+    message: {
+        subject?: string;
+        text: string;
+        attachments?: unknown[];
+        metadata?: Record<string, unknown>;
+    };
+    idempotencyKey: string;
+}
+interface DispatchResult {
+    messageId?: string;
+    deliveryStatus?: string;
+}
+interface AppProfile {
+    appId: string;
+    displayName: string;
+    domain: string;
+    extensions: AppExtension[];
+    eventContracts: string[];
+}
+type InboundEventType = 'connection.connected' | 'connection.disconnected' | 'connection.error' | 'task.created' | 'task.updated' | 'task.completed' | 'workspace.updated' | string;
+interface InboundEvent {
+    type: InboundEventType;
+    workspaceId: string;
+    userId?: string;
+    payload: Record<string, unknown>;
+    timestamp: string;
+}
+interface DataQuery {
+    tool: string;
+    workspaceId: string;
+    userId: string;
+    params: Record<string, unknown>;
+    requestId: string;
+}
+interface DataResponse {
+    requestId: string;
+    result?: unknown;
+    error?: string;
+}
+interface InboundHandlers {
+    onEvent?: (event: InboundEvent) => void | Promise<void>;
+    onDataQuery?: (query: DataQuery) => Promise<unknown>;
+}
+interface InboundVerifyResult {
+    ok: boolean;
+    error?: string;
+}
+interface TestConnectionResult {
+    ok: boolean;
+    latencyMs: number;
+    plexoVersion?: string;
+    error?: string;
+}
+
+declare class PlexoClient {
+    #private;
+    constructor(opts: PlexoClientOptions);
+    get appId(): string;
+    get isConfigured(): boolean;
+    register(): Promise<void>;
+    ensureWorkspace(userId: string, email?: string): Promise<string>;
+    getInstalledConnections(workspaceId: string): Promise<PlexoConnection[]>;
+    getToken(workspaceId: string, registryId: string): Promise<PlexoToken | null>;
+    disconnect(workspaceId: string, connectionId: string): Promise<void>;
+    oauthPopupUrl(provider: string, workspaceId: string): string;
+    aiComplete(workspaceId: string, opts: AiCompleteOptions): Promise<string>;
+    chatMessage(workspaceId: string, userId: string, opts: ChatOptions): Promise<ChatReply>;
+    dispatch(opts: DispatchOptions): Promise<DispatchResult>;
+    /** Returns a framework-agnostic handler for Plexo → app push requests. */
+    inbound(handlers: InboundHandlers): {
+        handle(req: Request): Promise<Response>;
+    };
+    testConnection(): Promise<TestConnectionResult>;
+}
+
+declare class PlexoNotConfiguredError extends Error {
+    readonly name = "PlexoNotConfiguredError";
+    constructor(missing: string);
+}
+declare class PlexoUnreachableError extends Error {
+    readonly name = "PlexoUnreachableError";
+    readonly url: string;
+    constructor(url: string, cause?: unknown);
+}
+declare class PlexoApiError extends Error {
+    readonly name: string;
+    readonly status: number;
+    readonly path: string;
+    constructor(status: number, path: string, detail?: string);
+}
+declare class PlexoAuthError extends PlexoApiError {
+    readonly name: "PlexoAuthError";
+    constructor(path: string);
+}
+declare class PlexoRateLimitedError extends PlexoApiError {
+    readonly name: "PlexoRateLimitedError";
+    readonly retryAfterMs: number;
+    constructor(path: string, retryAfterSec?: number);
+}
+
+declare function verifyInboundSignature(body: string, signature: string | null, timestamp: string | null, serviceKey: string): InboundVerifyResult;
+
+/**
+ * @plexo/sdk — connect module
+ *
+ * Universal client for connecting any app to Plexo Core.
+ *
+ * Quick start:
+ *
+ *   import { createPlexoClient } from '@joeybuilt/plexo-sdk/connect'
+ *
+ *   export const plexo = createPlexoClient({
+ *     appId:      process.env.APP_ID      ?? 'my-app',
+ *     plexoUrl:   process.env.PLEXO_URL   ?? '',
+ *     serviceKey: process.env.SERVICE_KEY ?? '',
+ *     extensions: [
+ *       { id: 'my-app.todos.list', type: 'tool', name: 'List Todos',
+ *         config: { description: 'List todos for the current user' } },
+ *     ],
+ *     eventContracts: ['my-app.todo.created'],
+ *   })
+ *
+ * Register at boot (Next.js instrumentation.ts, Express server start, etc.):
+ *   await plexo.register()
+ *
+ * Per-user workspace (call once on first login):
+ *   const workspaceId = await plexo.ensureWorkspace(userId, email)
+ *
+ * AI / chat:
+ *   const text = await plexo.aiComplete(workspaceId, { messages: [...] })
+ *   const reply = await plexo.chatMessage(workspaceId, userId, { message })
+ *
+ * Inbound events + data queries (mount at POST /api/plexo/events):
+ *   export const POST = (req: Request) =>
+ *     plexo.inbound({ onEvent, onDataQuery }).handle(req)
+ */
+
+/**
+ * Create a configured Plexo client.
+ * Call `await client.register()` once at app boot to announce this app to
+ * Plexo Core and make its extensions discoverable.
+ */
+declare function createPlexoClient(opts: PlexoClientOptions): PlexoClient;
+
+export { type AiCompleteOptions, type AiMessage, type AppChannelConfig, type AppConnectorConfig, type AppExtension, type AppProfile, type AppToolConfig, type ChatOptions, type ChatReply, type DataQuery, type DataResponse, type DispatchOptions, type DispatchResult, type InboundEvent, type InboundEventType, type InboundHandlers, type InboundVerifyResult, PlexoApiError, PlexoAuthError, PlexoClient, type PlexoClientOptions, type PlexoConnection, PlexoNotConfiguredError, PlexoRateLimitedError, type PlexoToken, PlexoUnreachableError, type ResilienceOptions, type TestConnectionResult, createPlexoClient, verifyInboundSignature };

package/dist/connect/index.js

@@ -0,0 +1,392 @@
+// src/connect/errors.ts
+var PlexoNotConfiguredError = class extends Error {
+  name = "PlexoNotConfiguredError";
+  constructor(missing) {
+    super(`PlexoClient not configured: ${missing} is required`);
+  }
+};
+var PlexoUnreachableError = class extends Error {
+  name = "PlexoUnreachableError";
+  url;
+  constructor(url, cause) {
+    super(`Plexo Core unreachable at ${url}`);
+    this.url = url;
+    if (cause) this.cause = cause;
+  }
+};
+var PlexoApiError = class extends Error {
+  name = "PlexoApiError";
+  status;
+  path;
+  constructor(status, path, detail) {
+    super(`Plexo API error ${status} on ${path}${detail ? `: ${detail}` : ""}`);
+    this.status = status;
+    this.path = path;
+  }
+};
+var PlexoAuthError = class extends PlexoApiError {
+  name = "PlexoAuthError";
+  constructor(path) {
+    super(401, path, "invalid or missing service key");
+  }
+};
+var PlexoRateLimitedError = class extends PlexoApiError {
+  name = "PlexoRateLimitedError";
+  retryAfterMs;
+  constructor(path, retryAfterSec) {
+    super(429, path, "rate limited");
+    this.retryAfterMs = (retryAfterSec ?? 60) * 1e3;
+  }
+};
+
+// src/connect/inbound.ts
+import { createHmac, timingSafeEqual } from "crypto";
+var SKEW_MS = 5 * 60 * 1e3;
+function verifyInboundSignature(body, signature, timestamp, serviceKey) {
+  if (!signature || !timestamp) {
+    return { ok: false, error: "missing X-Plexo-Signature or X-Plexo-Timestamp" };
+  }
+  const ts = Date.parse(timestamp);
+  if (Number.isNaN(ts) || Math.abs(Date.now() - ts) > SKEW_MS) {
+    return { ok: false, error: "timestamp skew exceeds 5 minutes" };
+  }
+  const expected = "sha256=" + createHmac("sha256", serviceKey).update(body).digest("hex");
+  const sigBuf = Buffer.from(signature);
+  const expBuf = Buffer.from(expected);
+  if (sigBuf.length !== expBuf.length || !timingSafeEqual(sigBuf, expBuf)) {
+    return { ok: false, error: "signature mismatch" };
+  }
+  return { ok: true };
+}
+function createInboundRouter(serviceKey, handlers) {
+  return {
+    async handle(req) {
+      const body = await req.text();
+      const sig = req.headers.get("x-plexo-signature");
+      const ts = req.headers.get("x-plexo-timestamp");
+      const check = verifyInboundSignature(body, sig, ts, serviceKey);
+      if (!check.ok) {
+        return new Response(
+          JSON.stringify({ error: check.error }),
+          { status: 401, headers: { "Content-Type": "application/json" } }
+        );
+      }
+      let parsed;
+      try {
+        parsed = JSON.parse(body);
+      } catch {
+        return new Response(
+          JSON.stringify({ error: "invalid JSON" }),
+          { status: 400, headers: { "Content-Type": "application/json" } }
+        );
+      }
+      const msg = parsed;
+      const kind = msg["kind"];
+      try {
+        if (kind === "event" && handlers.onEvent) {
+          await handlers.onEvent(msg["event"]);
+          return new Response(null, { status: 204 });
+        }
+        if (kind === "data_query" && handlers.onDataQuery) {
+          const query = msg["query"];
+          const result = await handlers.onDataQuery(query);
+          const response = { requestId: query.requestId, result };
+          return new Response(
+            JSON.stringify(response),
+            { status: 200, headers: { "Content-Type": "application/json" } }
+          );
+        }
+        return new Response(null, { status: 204 });
+      } catch (err) {
+        const response = {
+          requestId: msg["query"]?.requestId ?? "",
+          error: err instanceof Error ? err.message : String(err)
+        };
+        return new Response(
+          JSON.stringify(response),
+          { status: 500, headers: { "Content-Type": "application/json" } }
+        );
+      }
+    }
+  };
+}
+
+// src/connect/registration.ts
+function buildHeaders(opts) {
+  return {
+    "Content-Type": "application/json",
+    Authorization: `Bearer ${opts.serviceKey}`,
+    "X-App-Id": opts.appId
+  };
+}
+async function post(opts, path, body) {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  try {
+    const res = await fetchImpl(
+      `${opts.plexoUrl.replace(/\/$/, "")}${path}`,
+      {
+        method: "POST",
+        headers: buildHeaders(opts),
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(8e3)
+      }
+    );
+    if (!res.ok) {
+      const detail = await res.text().catch(() => `HTTP ${res.status}`);
+      console.error(`[plexo/connect] registration rejected (${res.status}): ${detail}`);
+      return false;
+    }
+    return true;
+  } catch (err) {
+    console.warn(`[plexo/connect] registration attempt failed: ${err.message}`);
+    return false;
+  }
+}
+async function register(opts, profile) {
+  const backoff = opts.resilience?.registrationBackoffMs ?? [5e3, 15e3, 45e3];
+  if (await post(opts, "/api/v1/profiles/register", profile)) {
+    console.info(`[plexo/connect] registered appId=${opts.appId}`);
+    return;
+  }
+  for (const delay of backoff) {
+    console.info(`[plexo/connect] retrying registration in ${delay / 1e3}s`);
+    await new Promise((r) => setTimeout(r, delay));
+    if (await post(opts, "/api/v1/profiles/register", profile)) {
+      console.info(`[plexo/connect] registered appId=${opts.appId}`);
+      return;
+    }
+  }
+  console.warn("[plexo/connect] registration retries exhausted \u2014 running in standalone mode");
+}
+
+// src/connect/client.ts
+var PlexoClient = class {
+  #opts;
+  #base;
+  constructor(opts) {
+    this.#opts = opts;
+    this.#base = opts.plexoUrl.replace(/\/$/, "");
+  }
+  get appId() {
+    return this.#opts.appId;
+  }
+  get isConfigured() {
+    return !!(this.#opts.plexoUrl && this.#opts.serviceKey);
+  }
+  // -----------------------------------------------------------------------
+  // Registration
+  // -----------------------------------------------------------------------
+  async register() {
+    if (!this.isConfigured) return;
+    let domain = "";
+    try {
+      domain = new URL(this.#opts.plexoUrl).host;
+    } catch {
+    }
+    const profile = {
+      appId: this.#opts.appId,
+      displayName: this.#opts.displayName ?? this.#opts.appId,
+      domain,
+      extensions: this.#opts.extensions ?? [],
+      eventContracts: this.#opts.eventContracts ?? []
+    };
+    await register(this.#opts, profile);
+  }
+  // -----------------------------------------------------------------------
+  // Workspace
+  // -----------------------------------------------------------------------
+  async ensureWorkspace(userId, email) {
+    const data = await this.#post(
+      "/api/v1/auth/workspace/ensure",
+      { userId, email, name: this.#opts.displayName ?? this.#opts.appId },
+      { userId }
+    );
+    return data.workspaceId;
+  }
+  // -----------------------------------------------------------------------
+  // Connections
+  // -----------------------------------------------------------------------
+  async getInstalledConnections(workspaceId) {
+    try {
+      const data = await this.#get(
+        `/api/v1/connections/installed?workspaceId=${encodeURIComponent(workspaceId)}`
+      );
+      return data.items ?? [];
+    } catch {
+      return [];
+    }
+  }
+  async getToken(workspaceId, registryId) {
+    try {
+      return await this.#get(
+        `/api/v1/connections/token?workspaceId=${encodeURIComponent(workspaceId)}&registryId=${encodeURIComponent(registryId)}`
+      );
+    } catch (err) {
+      if (err instanceof PlexoApiError && err.status === 404) return null;
+      throw err;
+    }
+  }
+  async disconnect(workspaceId, connectionId) {
+    await this.#delete(
+      `/api/v1/connections/installed/${encodeURIComponent(connectionId)}?workspaceId=${encodeURIComponent(workspaceId)}`
+    );
+  }
+  oauthPopupUrl(provider, workspaceId) {
+    return `${this.#base}/api/oauth/${encodeURIComponent(provider)}/start?workspaceId=${encodeURIComponent(workspaceId)}`;
+  }
+  // -----------------------------------------------------------------------
+  // AI
+  // -----------------------------------------------------------------------
+  async aiComplete(workspaceId, opts) {
+    const data = await this.#post(
+      "/api/v1/ai/complete",
+      { workspaceId, ...opts },
+      {},
+      3e4
+    );
+    return data.text ?? "";
+  }
+  async chatMessage(workspaceId, userId, opts) {
+    const data = await this.#post(
+      "/api/v1/chat/message",
+      { workspaceId, forceConversation: true, ...opts },
+      { userId },
+      3e4
+    );
+    return {
+      reply: data.reply ?? "",
+      conversationId: data.conversationId,
+      sessionId: data.sessionId,
+      taskId: data.taskId
+    };
+  }
+  // -----------------------------------------------------------------------
+  // Channel dispatch
+  // -----------------------------------------------------------------------
+  async dispatch(opts) {
+    const data = await this.#post(
+      "/api/v1/channel/dispatch",
+      opts
+    );
+    return { messageId: data.messageId, deliveryStatus: data.deliveryStatus };
+  }
+  // -----------------------------------------------------------------------
+  // Inbound
+  // -----------------------------------------------------------------------
+  /** Returns a framework-agnostic handler for Plexo → app push requests. */
+  inbound(handlers) {
+    return createInboundRouter(this.#opts.serviceKey, handlers);
+  }
+  // -----------------------------------------------------------------------
+  // Utilities
+  // -----------------------------------------------------------------------
+  async testConnection() {
+    const start = Date.now();
+    try {
+      const fetchImpl = this.#opts.fetchImpl ?? fetch;
+      const res = await fetchImpl(`${this.#base}/api/health`, {
+        signal: AbortSignal.timeout(5e3)
+      });
+      const latencyMs = Date.now() - start;
+      if (!res.ok) {
+        return { ok: false, latencyMs, error: `HTTP ${res.status}` };
+      }
+      const body = await res.json().catch(() => ({}));
+      return { ok: true, latencyMs, plexoVersion: body["version"] };
+    } catch (err) {
+      return {
+        ok: false,
+        latencyMs: Date.now() - start,
+        error: err instanceof Error ? err.message : String(err)
+      };
+    }
+  }
+  // -----------------------------------------------------------------------
+  // HTTP helpers
+  // -----------------------------------------------------------------------
+  #headers(extra = {}) {
+    const h = {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${this.#opts.serviceKey}`,
+      "X-App-Id": this.#opts.appId
+    };
+    if (extra.userId) h["X-User-Id"] = extra.userId;
+    return h;
+  }
+  async #get(path) {
+    const fetchImpl = this.#opts.fetchImpl ?? fetch;
+    const timeout = this.#opts.resilience?.timeoutMs ?? 15e3;
+    let res;
+    try {
+      res = await fetchImpl(`${this.#base}${path}`, {
+        headers: this.#headers(),
+        signal: AbortSignal.timeout(timeout)
+      });
+    } catch (err) {
+      throw new PlexoUnreachableError(this.#base, err);
+    }
+    return this.#parse(res, path);
+  }
+  async #post(path, body, extra = {}, timeoutMs) {
+    const fetchImpl = this.#opts.fetchImpl ?? fetch;
+    const timeout = timeoutMs ?? this.#opts.resilience?.timeoutMs ?? 15e3;
+    let res;
+    try {
+      res = await fetchImpl(`${this.#base}${path}`, {
+        method: "POST",
+        headers: this.#headers(extra),
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(timeout)
+      });
+    } catch (err) {
+      throw new PlexoUnreachableError(this.#base, err);
+    }
+    return this.#parse(res, path);
+  }
+  async #delete(path) {
+    const fetchImpl = this.#opts.fetchImpl ?? fetch;
+    const timeout = this.#opts.resilience?.timeoutMs ?? 15e3;
+    let res;
+    try {
+      res = await fetchImpl(`${this.#base}${path}`, {
+        method: "DELETE",
+        headers: this.#headers(),
+        signal: AbortSignal.timeout(timeout)
+      });
+    } catch (err) {
+      throw new PlexoUnreachableError(this.#base, err);
+    }
+    if (!res.ok && res.status !== 404) {
+      await this.#parse(res, path);
+    }
+  }
+  async #parse(res, path) {
+    if (res.status === 401) throw new PlexoAuthError(path);
+    if (res.status === 429) {
+      const retry = Number(res.headers.get("retry-after"));
+      throw new PlexoRateLimitedError(path, Number.isNaN(retry) ? void 0 : retry);
+    }
+    if (!res.ok) {
+      const detail = await res.text().catch(() => "");
+      throw new PlexoApiError(res.status, path, detail.slice(0, 300));
+    }
+    if (res.status === 204) return void 0;
+    return res.json();
+  }
+};
+
+// src/connect/index.ts
+function createPlexoClient(opts) {
+  return new PlexoClient(opts);
+}
+export {
+  PlexoApiError,
+  PlexoAuthError,
+  PlexoClient,
+  PlexoNotConfiguredError,
+  PlexoRateLimitedError,
+  PlexoUnreachableError,
+  createPlexoClient,
+  verifyInboundSignature
+};
+//# sourceMappingURL=index.js.map