open-mcp-app 0.1.0 → 0.1.2

package/index.js

@@ -1,363 +0,0 @@
-'use strict';
-
-/**
- * Ensures a value is a non-empty string so that the SDK fails fast with a
- * consistent error message. This keeps downstream network errors from masking
- * configuration mistakes and makes SDK usage easier to debug.
- *
- * @param {Object} args
- * @param {unknown} args.value
- * @param {string} args.name
- * @returns {string}
- */
-const assertNonEmptyString = ({ value, name } = {}) => {
-  if (typeof value !== 'string' || value.trim().length === 0) {
-    throw new McpAppsSdkError({
-      message: `${name} must be a non-empty string.`,
-      code: 'MCP_APPS_INVALID_ARGUMENT',
-    });
-  }
-
-  return value;
-};
-
-/**
- * Normalizes a base URL by removing trailing slashes so that URL construction is
- * predictable. This avoids subtle double-slash URLs when callers pass a base
- * URL like "https://api.example.com/".
- *
- * @param {Object} args
- * @param {string} args.baseUrl
- * @returns {string}
- */
-const normalizeBaseUrl = ({ baseUrl } = {}) => {
-  const url = assertNonEmptyString({ value: baseUrl, name: 'baseUrl' });
-  return url.replace(/\/+$/, '');
-};
-
-/**
- * Builds a request URL from a base URL, a path, and an optional query object.
- * Centralizing URL construction ensures consistent encoding rules across the
- * SDK and reduces the chance of introducing subtle request bugs.
- *
- * @param {Object} args
- * @param {string} args.baseUrl
- * @param {string} args.path
- * @param {Object<string, string | number | boolean | null | undefined>} [args.query]
- * @returns {string}
- */
-const buildUrl = ({ baseUrl, path, query } = {}) => {
-  const normalizedBaseUrl = normalizeBaseUrl({ baseUrl });
-  const normalizedPath = assertNonEmptyString({ value: path, name: 'path' }).startsWith('/')
-    ? path
-    : `/${path}`;
-
-  const url = new URL(`${normalizedBaseUrl}${normalizedPath}`);
-
-  if (query && typeof query === 'object') {
-    for (const [key, value] of Object.entries(query)) {
-      if (value === undefined || value === null) continue;
-      url.searchParams.set(key, String(value));
-    }
-  }
-
-  return url.toString();
-};
-
-/**
- * A base error type for the SDK so that callers can reliably distinguish
- * expected SDK failures from other runtime errors.
- */
-class McpAppsSdkError extends Error {
-  /**
-   * Creates a new SDK error instance.
-   *
-   * @param {Object} args
-   * @param {string} args.message
-   * @param {string} [args.code]
-   * @param {unknown} [args.cause]
-   */
-  constructor({ message, code, cause } = {}) {
-    super(message);
-    this.name = 'McpAppsSdkError';
-    this.code = code || 'MCP_APPS_SDK_ERROR';
-
-    if (cause !== undefined) {
-      this.cause = cause;
-    }
-  }
-}
-
-/**
- * An error thrown when an HTTP request completes but returns an unsuccessful
- * status code. Surfacing the URL, method, status, and response body makes it
- * straightforward to debug API failures without requiring extra logging.
- */
-class McpAppsRequestError extends McpAppsSdkError {
-  /**
-   * Creates a request error for a failed HTTP response.
-   *
-   * @param {Object} args
-   * @param {string} args.message
-   * @param {string} args.method
-   * @param {string} args.url
-   * @param {number} args.status
-   * @param {unknown} [args.body]
-   */
-  constructor({ message, method, url, status, body } = {}) {
-    super({ message, code: 'MCP_APPS_REQUEST_FAILED' });
-    this.name = 'McpAppsRequestError';
-    this.method = method;
-    this.url = url;
-    this.status = status;
-    this.body = body;
-  }
-}
-
-/**
- * Creates a new `McpAppsClient` instance.
- *
- * This factory exists so consumers can create clients without `new`, which is
- * a common ergonomic pattern for SDKs and helps keep usage consistent across
- * codebases.
- *
- * @param {Object} args
- * @param {string} args.baseUrl
- * @param {string} [args.apiKey]
- * @param {(input: string, init?: Object) => Promise<Response>} [args.fetchFn]
- * @param {string} [args.userAgent]
- * @returns {McpAppsClient}
- */
-const createMcpAppsClient = ({ baseUrl, apiKey, fetchFn, userAgent } = {}) =>
-  new McpAppsClient({ baseUrl, apiKey, fetchFn, userAgent });
-
-/**
- * A small, opinionated client that demonstrates the shape of an open MCP Apps SDK.
- *
- * The class stays intentionally lightweight: it provides a generic `request`
- * primitive plus a few convenience methods that map to typical discovery and
- * invocation workflows. The goal is to provide stable call signatures and
- * error shapes even while the backing API evolves.
- */
-class McpAppsClient {
-  /**
-   * Creates a new client instance.
-   *
-   * @param {Object} args
-   * @param {string} args.baseUrl
-   * @param {string} [args.apiKey]
-   * @param {(input: string, init?: Object) => Promise<Response>} [args.fetchFn]
-   * @param {string} [args.userAgent]
-   */
-  constructor({ baseUrl, apiKey, fetchFn, userAgent } = {}) {
-    this._baseUrl = normalizeBaseUrl({ baseUrl });
-    this._apiKey = apiKey;
-    this._fetchFn = fetchFn;
-    this._userAgent = userAgent;
-  }
-
-  /**
-   * Updates client configuration at runtime.
-   *
-   * This exists so applications can construct a client early and later inject
-   * credentials or a custom fetch implementation without needing to pass the
-   * client instance through additional layers.
-   *
-   * @param {Object} args
-   * @param {string} [args.baseUrl]
-   * @param {string} [args.apiKey]
-   * @param {(input: string, init?: Object) => Promise<Response>} [args.fetchFn]
-   * @param {string} [args.userAgent]
-   * @returns {void}
-   */
-  configure = ({ baseUrl, apiKey, fetchFn, userAgent } = {}) => {
-    if (baseUrl !== undefined) this._baseUrl = normalizeBaseUrl({ baseUrl });
-    if (apiKey !== undefined) this._apiKey = apiKey;
-    if (fetchFn !== undefined) this._fetchFn = fetchFn;
-    if (userAgent !== undefined) this._userAgent = userAgent;
-  };
-
-  /**
-   * Issues an HTTP request and returns the parsed response body.
-   *
-   * The method is designed to be the lowest-level primitive in this SDK:
-   * higher-level helpers call into `request` so that retry, logging, custom
-   * headers, and transport behaviors can be added in one place.
-   *
-   * @param {Object} args
-   * @param {string} [args.method]
-   * @param {string} args.path
-   * @param {Object<string, string | number | boolean | null | undefined>} [args.query]
-   * @param {Object<string, string>} [args.headers]
-   * @param {unknown} [args.body]
-   * @param {AbortSignal} [args.signal]
-   * @returns {Promise<unknown>}
-   */
-  request = async ({ method, path, query, headers, body, signal } = {}) => {
-    const url = buildUrl({ baseUrl: this._baseUrl, path, query });
-
-    const fetchFn = this._fetchFn || globalThis.fetch;
-    if (typeof fetchFn !== 'function') {
-      throw new McpAppsSdkError({
-        message:
-          'No fetch implementation is available. Provide fetchFn or use Node.js 18+ where fetch is built in.',
-        code: 'MCP_APPS_MISSING_FETCH',
-      });
-    }
-
-    const normalizedMethod = (method || 'GET').toUpperCase();
-
-    const requestHeaders = {
-      ...(headers || {}),
-    };
-
-    if (this._userAgent && !requestHeaders['user-agent'] && !requestHeaders['User-Agent']) {
-      requestHeaders['user-agent'] = this._userAgent;
-    }
-
-    if (this._apiKey && !requestHeaders.authorization && !requestHeaders.Authorization) {
-      requestHeaders.authorization = `Bearer ${this._apiKey}`;
-    }
-
-    /** @type {Object} */
-    const init = { method: normalizedMethod, headers: requestHeaders, signal };
-
-    if (body !== undefined) {
-      if (!requestHeaders['content-type'] && !requestHeaders['Content-Type']) {
-        requestHeaders['content-type'] = 'application/json';
-      }
-
-      init.body =
-        typeof body === 'string' || Buffer.isBuffer(body) ? body : JSON.stringify(body);
-    }
-
-    const response = await fetchFn(url, init);
-
-    const contentType = response.headers?.get?.('content-type') || '';
-    const isJson = contentType.toLowerCase().includes('application/json');
-
-    const responseBody = isJson
-      ? await response.json().catch(() => undefined)
-      : await response.text();
-
-    if (!response.ok) {
-      throw new McpAppsRequestError({
-        message: `Request failed with status ${response.status}.`,
-        method: normalizedMethod,
-        url,
-        status: response.status,
-        body: responseBody,
-      });
-    }
-
-    return responseBody;
-  };
-
-  /**
-   * Lists apps accessible to the current principal from the "open apps" surface.
-   *
-   * This method exists as a convenience helper for discovery flows. Routing
-   * through a dedicated open path keeps the intention clear for callers and
-   * allows backend policies to evolve independently from non-open app surfaces.
-   *
-   * @param {Object} args
-   * @param {AbortSignal} [args.signal]
-   * @returns {Promise<unknown>}
-   */
-  listApps = async ({ signal } = {}) =>
-    this.request({ method: 'GET', path: '/open/apps', signal });
-
-  /**
-   * Fetches a single open app by id.
-   *
-   * Explicitly requiring `appId` keeps the call signature self-documenting and
-   * avoids ambiguous positional parameters.
-   *
-   * @param {Object} args
-   * @param {string} args.appId
-   * @param {AbortSignal} [args.signal]
-   * @returns {Promise<unknown>}
-   */
-  getApp = async ({ appId, signal } = {}) => {
-    const id = assertNonEmptyString({ value: appId, name: 'appId' });
-    return this.request({ method: 'GET', path: `/open/apps/${encodeURIComponent(id)}`, signal });
-  };
-
-  /**
-   * Fetches an open app's manifest.
-   *
-   * Manifests are commonly used to describe capabilities (tools, input schema,
-   * output schema) without requiring execution. Exposing this as a separate
-   * call keeps discovery lightweight and avoids overloading `getApp`.
-   *
-   * @param {Object} args
-   * @param {string} args.appId
-   * @param {AbortSignal} [args.signal]
-   * @returns {Promise<unknown>}
-   */
-  getAppManifest = async ({ appId, signal } = {}) => {
-    const id = assertNonEmptyString({ value: appId, name: 'appId' });
-    return this.request({
-      method: 'GET',
-      path: `/open/apps/${encodeURIComponent(id)}/manifest`,
-      signal,
-    });
-  };
-
-  /**
-   * Runs an open app with an input payload.
-   *
-   * Many MCP-style "apps" are orchestrations that accept structured input and
-   * return structured output. This method provides a stable entry point for
-   * that interaction while keeping transport details inside `request`.
-   *
-   * @param {Object} args
-   * @param {string} args.appId
-   * @param {unknown} [args.input]
-   * @param {AbortSignal} [args.signal]
-   * @returns {Promise<unknown>}
-   */
-  runApp = async ({ appId, input, signal } = {}) => {
-    const id = assertNonEmptyString({ value: appId, name: 'appId' });
-    return this.request({
-      method: 'POST',
-      path: `/open/apps/${encodeURIComponent(id)}/run`,
-      body: { input },
-      signal,
-    });
-  };
-
-  /**
-   * Invokes a tool exposed by an open app.
-   *
-   * Tools are a core MCP primitive. This method intentionally accepts `args`
-   * as an object so that tool invocation stays forward-compatible when tool
-   * schemas evolve.
-   *
-   * @param {Object} args
-   * @param {string} args.appId
-   * @param {string} args.toolName
-   * @param {Object<string, unknown>} [args.args]
-   * @param {AbortSignal} [args.signal]
-   * @returns {Promise<unknown>}
-   */
-  invokeTool = async ({ appId, toolName, args, signal } = {}) => {
-    const id = assertNonEmptyString({ value: appId, name: 'appId' });
-    const tool = assertNonEmptyString({ value: toolName, name: 'toolName' });
-
-    return this.request({
-      method: 'POST',
-      path: `/open/apps/${encodeURIComponent(id)}/tools/${encodeURIComponent(tool)}`,
-      body: { args: args || {} },
-      signal,
-    });
-  };
-}
-
-module.exports = {
-  McpAppsSdkError,
-  McpAppsRequestError,
-  McpAppsClient,
-  createMcpAppsClient,
-};
-