@lemonmade/ucp-schema 0.0.0-preview-20260123174501

package/build/esnext/compose.esnext

@@ -0,0 +1,298 @@
+class UcpSchemaComposer {
+  /**
+   * Create a composed schema from a UCP profile. This function will look
+   * at the capabilities and payment handlers in the profile, fetch the
+   * JSON schemas (and any JSON schemas referenced within), and return an
+   * object that allows you to get a composed schema for a specific file
+   * and UCP operation.
+   */
+  static async fromProfile({ ucp: { capabilities } }, {
+    fetch: fetchSchema = createDefaultSchemaFetcher()
+  } = {}) {
+    const resolvedCapabilities = await Promise.all(
+      capabilities.map(async (capability) => {
+        let json;
+        const schemaUrl = new URL(capability.schema);
+        const reverseDnsForUrl = schemaUrl.hostname.split(".").reverse().join(".");
+        if (!capability.name.startsWith(reverseDnsForUrl)) {
+          throw new Error(
+            `Invalid schema name: ${capability.name} does not match URL ${capability.schema}`
+          );
+        }
+        try {
+          json = await fetchSchema(capability.schema);
+        } catch (error) {
+          throw new Error(`Schema not found for URL: ${capability.schema}`);
+        }
+        return {
+          capability,
+          schema: json
+        };
+      })
+    );
+    return new UcpSchemaComposer({
+      capabilities: resolvedCapabilities
+    });
+  }
+  #profile;
+  #profileNameToUrlMap = /* @__PURE__ */ new Map();
+  #profileUrlToCapabilityMap = /* @__PURE__ */ new Map();
+  #schemaMapByOperation = /* @__PURE__ */ new Map();
+  constructor(profile) {
+    this.#profile = profile;
+    for (const { capability } of profile.capabilities) {
+      this.#profileNameToUrlMap.set(capability.name, capability.schema);
+      this.#profileUrlToCapabilityMap.set(capability.schema, capability);
+    }
+  }
+  /**
+   * Get a schema file composer for the specified schema URL.
+   *
+   * @param schema - The schema URL or capability name
+   * @returns A UcpSchemaComposerFile instance, or undefined if not found
+   */
+  get(schema) {
+    const url = this.#profileNameToUrlMap.get(schema) ?? schema;
+    const capability = this.#profileUrlToCapabilityMap.get(url);
+    if (capability == null) return void 0;
+    return new UcpSchemaComposerFile(url, { capability, composer: this });
+  }
+  /**
+   * Get all schema entries for a specific operation.
+   *
+   * @param options - Options for getting entries
+   * @param options.operation - The operation context
+   * @returns An iterator of schema URL and composed schema pairs
+   */
+  entries({ operation = "read" } = {}) {
+    return this.#schemaMapForOperation(operation).entries();
+  }
+  /**
+   * Internal method to get the composed schema directly.
+   * Used by UcpSchemaComposerFile.
+   */
+  composedSchema(schema, { operation = "read" } = {}) {
+    return this.#schemaMapForOperation(operation).get(schema);
+  }
+  #schemaMapForOperation(operation) {
+    let schemaMap = this.#schemaMapByOperation.get(operation);
+    if (schemaMap == null) {
+      schemaMap = createSchemaMap(this.#profile, { operation });
+    }
+    return schemaMap;
+  }
+}
+class UcpSchemaComposerFile {
+  #url;
+  #composer;
+  capability;
+  constructor(url, {
+    composer,
+    capability
+  }) {
+    this.#url = url;
+    this.#composer = composer;
+    this.capability = capability;
+  }
+  /**
+   * Get the composed schema for a specific operation.
+   */
+  composedSchema(options) {
+    const schema = this.#composer.composedSchema(this.#url, options);
+    if (schema == null) {
+      throw new ReferenceError(`Schema not found for URL: ${this.#url}`);
+    }
+    return schema;
+  }
+}
+function createSchemaMap({ capabilities }, { operation }) {
+  const schemaMap = /* @__PURE__ */ new Map();
+  const schemaNameToUrlMap = /* @__PURE__ */ new Map();
+  for (const { capability, schema } of capabilities) {
+    schemaNameToUrlMap.set(capability.name, capability.schema);
+    const clonedSchema = structuredClone(schema);
+    processSchemaUcpMetadata(clonedSchema, operation);
+    schemaMap.set(capability.schema, clonedSchema);
+    if (capability.extends == null) continue;
+    const defs = clonedSchema.$defs;
+    const extendedSchemas = Array.isArray(capability.extends) ? capability.extends : [capability.extends];
+    for (const extendedSchemaName of extendedSchemas) {
+      const extensionDef = defs?.[extendedSchemaName];
+      if (extensionDef?.allOf == null) continue;
+      const extendedSchemaUrl = schemaNameToUrlMap.get(extendedSchemaName);
+      const extendedSchema = extendedSchemaUrl ? schemaMap.get(extendedSchemaUrl) : void 0;
+      if (extendedSchema == null) continue;
+      if (extendedSchema.allOf?.[0]?.$ref !== `#/$defs/${extendedSchemaName}`) {
+        const newDef = {
+          type: "object",
+          title: `${extendedSchema.title ?? extendedSchemaName} (base)`,
+          ...extendedSchema.properties ? { properties: extendedSchema.properties } : {},
+          ...extendedSchema.required ? { required: extendedSchema.required } : {},
+          ...extendedSchema.items ? { items: extendedSchema.items } : {},
+          ...extendedSchema.allOf ? { allOf: extendedSchema.allOf } : {},
+          ...extendedSchema.oneOf ? { oneOf: extendedSchema.oneOf } : {}
+        };
+        extendedSchema.$defs ??= {};
+        extendedSchema.$defs[extendedSchemaName] = newDef;
+        extendedSchema.allOf = [
+          { type: "object", $ref: `#/$defs/${extendedSchemaName}` }
+        ];
+        delete extendedSchema.properties;
+        delete extendedSchema.required;
+        delete extendedSchema.items;
+        delete extendedSchema.oneOf;
+      }
+      const clonedDefs = structuredClone(defs);
+      const filtereExtensionDefAllOf = extensionDef.allOf.filter(
+        ({ $ref }) => $ref == null || new URL($ref, capability.schema).href !== extendedSchemaUrl
+      );
+      if (filtereExtensionDefAllOf.length > 1) {
+        clonedDefs[extendedSchemaName] = {
+          type: "object",
+          allOf: filtereExtensionDefAllOf
+        };
+      } else {
+        const { allOf, ...rest } = extensionDef;
+        clonedDefs[extendedSchemaName] = {
+          type: "object",
+          ...rest,
+          ...filtereExtensionDefAllOf[0]
+        };
+      }
+      for (const otherExtendedSchemaName of extendedSchemas) {
+        if (otherExtendedSchemaName === extendedSchemaName) continue;
+        delete clonedDefs[otherExtendedSchemaName];
+      }
+      Object.assign(
+        extendedSchema.$defs,
+        namespaceExtensionDefs(clonedDefs, capability)
+      );
+      extendedSchema.allOf.push({
+        type: "object",
+        $ref: `#/$defs/${namespaceIdentifier(extendedSchemaName, capability)}`
+      });
+    }
+  }
+  return {
+    get(schema) {
+      if (schemaNameToUrlMap.has(schema)) {
+        return schemaMap.get(schemaNameToUrlMap.get(schema));
+      }
+      return schemaMap.get(schema);
+    },
+    entries() {
+      return schemaMap.entries();
+    }
+  };
+}
+function processSchemaUcpMetadata(schema, operation) {
+  let requiredNeedsUpdate = false;
+  const updatedRequired = new Set(schema.required);
+  if (schema.properties != null) {
+    for (const [key, value] of Object.entries(schema.properties)) {
+      processSchemaUcpMetadata(value, operation);
+      if (value.ucp_request == null) continue;
+      const ucpRequest = typeof value.ucp_request === "string" ? value.ucp_request : value.ucp_request[operation];
+      delete value.ucp_request;
+      if (operation === "read") continue;
+      switch (ucpRequest) {
+        case "omit":
+          delete schema.properties[key];
+          if (updatedRequired.has(key)) {
+            requiredNeedsUpdate = true;
+            updatedRequired.delete(key);
+          }
+          break;
+        case "required":
+          if (!updatedRequired.has(key)) {
+            requiredNeedsUpdate = true;
+            updatedRequired.add(key);
+          }
+          break;
+        case "optional":
+          if (updatedRequired.has(key)) {
+            requiredNeedsUpdate = true;
+            updatedRequired.delete(key);
+          }
+          break;
+      }
+    }
+  }
+  if (requiredNeedsUpdate) {
+    schema.required = Array.from(updatedRequired);
+  }
+  if (schema.items != null) {
+    if (Array.isArray(schema.items)) {
+      for (const item of schema.items) {
+        processSchemaUcpMetadata(item, operation);
+      }
+    } else {
+      processSchemaUcpMetadata(schema.items, operation);
+    }
+  }
+  if (schema.allOf != null) {
+    for (const allOfSchema of schema.allOf) {
+      processSchemaUcpMetadata(allOfSchema, operation);
+    }
+  }
+  if (schema.oneOf != null) {
+    for (const oneOfSchema of schema.oneOf) {
+      processSchemaUcpMetadata(oneOfSchema, operation);
+    }
+  }
+  if (schema.$defs != null) {
+    for (const value of Object.values(schema.$defs)) {
+      processSchemaUcpMetadata(value, operation);
+    }
+  }
+  return schema;
+}
+function namespaceIdentifier(identifier, capability) {
+  return `${capability.name}~${identifier}`;
+}
+function namespaceExtensionDefs(defs, capability) {
+  const newDefs = {};
+  for (const [key, value] of Object.entries(defs)) {
+    newDefs[namespaceIdentifier(key, capability)] = updateRefsWithNamespace(
+      value,
+      capability
+    );
+  }
+  return newDefs;
+}
+function updateRefsWithNamespace(obj, capability) {
+  if (obj === null || typeof obj !== "object") {
+    return obj;
+  }
+  if (Array.isArray(obj)) {
+    return obj.map((item) => updateRefsWithNamespace(item, capability));
+  }
+  const cloned = obj;
+  for (const [key, value] of Object.entries(obj)) {
+    if (key === "$ref" && typeof value === "string") {
+      const match = value.match(/^#\/\$defs\/(.+)$/);
+      if (match?.[1]) {
+        cloned[key] = `#/$defs/${namespaceIdentifier(match[1], capability)}`;
+      } else {
+        cloned[key] = value;
+      }
+    } else {
+      cloned[key] = updateRefsWithNamespace(value, capability);
+    }
+  }
+  return cloned;
+}
+function createDefaultSchemaFetcher() {
+  const cache = /* @__PURE__ */ new Map();
+  return (url) => {
+    const cached = cache.get(url);
+    if (cached) {
+      return cached;
+    }
+    const promise = fetch(url).then((response) => response.json());
+    cache.set(url, promise);
+    return promise;
+  };
+}
+
+export { UcpSchemaComposer, UcpSchemaComposerFile };

package/build/esnext/index.esnext

@@ -0,0 +1 @@
+export { UcpSchemaComposer } from './compose.esnext';

package/build/esnext/mcp.esnext

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+
+function jsonSchemaToOutputSchema(baseSchema) {
+  const { properties, required } = flattenJsonSchema(baseSchema);
+  const requiredProperties = new Set(required);
+  const outputSchema = {};
+  for (const [propertyName, propertySchema] of Object.entries(properties)) {
+    const zodType = z.fromJSONSchema(
+      {
+        $schema: "https://json-schema.org/draft/2020-12/schema",
+        ...propertySchema,
+        $defs: baseSchema.$defs
+      },
+      { defaultTarget: "openapi-3.0" }
+    );
+    outputSchema[propertyName] = requiredProperties.has(propertyName) ? zodType : zodType.optional();
+  }
+  return outputSchema;
+}
+function flattenJsonSchema(baseSchema) {
+  const properties = {};
+  const required = /* @__PURE__ */ new Set();
+  const mergedSchemas = [
+    baseSchema,
+    ...(baseSchema.allOf ?? []).flatMap((schema) => {
+      if (schema.properties) {
+        return schema;
+      }
+      if (schema.$ref?.startsWith("#/$defs/")) {
+        return baseSchema.$defs?.[schema.$ref.slice("#/$defs/".length)] ?? [];
+      }
+      return [];
+    })
+  ];
+  for (const schema of mergedSchemas) {
+    if (schema.properties) {
+      Object.assign(properties, schema.properties);
+    }
+    if (schema.required) {
+      for (const requiredPropertyName of schema.required) {
+        required.add(requiredPropertyName);
+      }
+    }
+  }
+  return {
+    properties,
+    required: Array.from(required)
+  };
+}
+
+export { jsonSchemaToOutputSchema };

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@lemonmade/ucp-schema",
+  "description": "Tools for composing Universal Commerce Protocol (UCP) schemas",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "@lemonmade/registry": "https://registry.npmjs.org"
+  },
+  "version": "0.0.0-preview-20260123174501",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/<USER>/<REPOSITORY>",
+    "directory": "packages/ucp-schema"
+  },
+  "exports": {
+    ".": {
+      "types": "./build/typescript/index.d.ts",
+      "quilt:source": "./source/index.ts",
+      "quilt:esnext": "./build/esnext/index.esnext",
+      "import": "./build/esm/index.mjs"
+    },
+    "./mcp": {
+      "types": "./build/typescript/mcp.d.ts",
+      "quilt:source": "./source/mcp.ts",
+      "quilt:esnext": "./build/esnext/mcp.esnext",
+      "import": "./build/esm/mcp.mjs"
+    }
+  },
+  "types": "./build/typescript/index.d.ts",
+  "sideEffects": false,
+  "dependencies": {},
+  "peerDependencies": {
+    "zod": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "zod": "^4.3.0"
+  },
+  "browserslist": [
+    "defaults and fully supports es6-module",
+    "maintained node versions"
+  ],
+  "scripts": {
+    "build": "rollup --config ./rollup.config.js"
+  }
+}

package/rollup.config.js

@@ -0,0 +1,3 @@
+import {quiltPackage} from '@quilted/rollup/package';
+
+export default quiltPackage();