@402md/skillmd 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,331 @@
+interface SkillManifest {
+    name: string;
+    displayName?: string;
+    description: string;
+    version?: string;
+    author?: string;
+    base_url: string;
+    type: SkillType;
+    payment: PaymentConfig;
+    endpoints: EndpointSpec[];
+    tags?: string[];
+    category?: string;
+    sla?: string;
+    rateLimit?: string;
+    sandbox?: string;
+    body: string;
+}
+interface PaymentConfig {
+    networks: PaymentNetwork[];
+    asset: string;
+    payTo: string;
+    payToEvm?: string;
+    facilitator?: string;
+}
+interface EndpointSpec {
+    path: string;
+    method: HttpMethod;
+    description: string;
+    priceUsdc: string;
+    inputSchema?: JSONSchema;
+    outputSchema?: JSONSchema;
+}
+type SkillType = 'API' | 'SAAS' | 'PRODUCT' | 'SERVICE' | 'SUBSCRIPTION' | 'CONTENT';
+type PaymentNetwork = 'stellar' | 'base' | 'base-sepolia' | 'stellar-testnet';
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+type JSONSchema = Record<string, unknown>;
+interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+    warnings: ValidationWarning[];
+}
+interface ValidationError {
+    field: string;
+    message: string;
+    code: string;
+}
+interface ValidationWarning {
+    field: string;
+    message: string;
+    code: string;
+}
+interface SkillConfig {
+    name: string;
+    displayName?: string;
+    description: string;
+    version?: string;
+    author?: string;
+    base_url: string;
+    type?: SkillType;
+    payment: PaymentConfig;
+    endpoints: EndpointSpec[];
+    tags?: string[];
+    category?: string;
+    sla?: string;
+    rateLimit?: string;
+    sandbox?: string;
+    body?: string;
+}
+interface OpenAPISpec {
+    openapi: string;
+    info: {
+        title: string;
+        description?: string;
+        version: string;
+    };
+    servers?: {
+        url: string;
+    }[];
+    paths: Record<string, OpenAPIPathItem>;
+}
+interface OpenAPIPathItem {
+    get?: OpenAPIOperation;
+    post?: OpenAPIOperation;
+    put?: OpenAPIOperation;
+    delete?: OpenAPIOperation;
+    patch?: OpenAPIOperation;
+}
+interface OpenAPIOperation {
+    summary?: string;
+    description?: string;
+    operationId?: string;
+    requestBody?: {
+        content?: Record<string, {
+            schema?: JSONSchema;
+        }>;
+    };
+    responses?: Record<string, {
+        description?: string;
+        content?: Record<string, {
+            schema?: JSONSchema;
+        }>;
+    }>;
+}
+interface LegacyFrontmatter {
+    name: string;
+    base_url?: string;
+    type?: string;
+    description?: string;
+    endpoints?: {
+        path: string;
+        method: string;
+        price?: string;
+        description?: string;
+    }[];
+    [key: string]: unknown;
+}
+
+/**
+ * Parse a SKILL.md string into a SkillManifest.
+ * Supports both v2 (with payment block) and v1 (legacy) formats.
+ */
+declare function parseSkillMd(content: string): SkillManifest;
+/**
+ * Extract raw frontmatter data and body from a SKILL.md string.
+ * Lower-level than parseSkillMd — returns unprocessed YAML data.
+ */
+declare function parseFrontmatter(md: string): {
+    data: LegacyFrontmatter;
+    body: string;
+};
+
+/**
+ * Validate a SkillManifest (already parsed).
+ */
+declare function validateSkill(manifest: SkillManifest): ValidationResult;
+/**
+ * Validate a raw SKILL.md string (parse + validate).
+ */
+declare function validateSkillMd(content: string): ValidationResult;
+
+/**
+ * Generate a SKILL.md string from a SkillConfig.
+ */
+declare function generateSkillMd(config: SkillConfig): string;
+/**
+ * Convert an OpenAPI spec into a SkillManifest.
+ * Each path+method becomes an endpoint in the manifest.
+ */
+declare function generateFromOpenAPI(spec: OpenAPISpec, payment: PaymentConfig, options?: {
+    defaultPrice?: string;
+    baseUrlOverride?: string;
+    /** Per-endpoint pricing. Keys: 'METHOD /path' or '*' for fallback. */
+    pricing?: Record<string, string>;
+}): SkillManifest;
+/**
+ * Convert a SkillManifest into an OpenAPI 3.0 spec.
+ * Reverse of generateFromOpenAPI.
+ */
+declare function toOpenAPI(manifest: SkillManifest): OpenAPISpec;
+
+/**
+ * MCP tool definition shape.
+ * Defined inline to avoid depending on @modelcontextprotocol/sdk.
+ */
+interface McpToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+/**
+ * Convert a SkillManifest into MCP tool definitions.
+ * Each endpoint becomes one tool.
+ */
+declare function toMcpToolDefinitions(manifest: SkillManifest): McpToolDefinition[];
+
+/**
+ * JSON Schema for SKILL.md v2 frontmatter validation.
+ * Can be used with any JSON Schema validator (ajv, zod, etc).
+ *
+ * Enums are derived from the shared constants in constants.ts
+ * so they stay in sync with the parser and validator.
+ */
+declare const SKILLMD_JSON_SCHEMA: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly title: "SKILL.md Frontmatter";
+    readonly description: "Schema for the YAML frontmatter in a SKILL.md file";
+    readonly type: "object";
+    readonly required: readonly ["name", "description", "base_url", "payment", "endpoints"];
+    readonly properties: {
+        readonly name: {
+            readonly type: "string";
+            readonly pattern: "^[a-z0-9][a-z0-9_-]*$";
+            readonly minLength: 1;
+            readonly maxLength: 100;
+            readonly description: "Unique skill identifier (kebab-case)";
+        };
+        readonly displayName: {
+            readonly type: "string";
+            readonly maxLength: 200;
+            readonly description: "Human-readable name";
+        };
+        readonly description: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly maxLength: 2000;
+            readonly description: "What this skill does";
+        };
+        readonly version: {
+            readonly type: "string";
+            readonly pattern: "^\\d+\\.\\d+\\.\\d+";
+            readonly description: "Semantic version";
+        };
+        readonly author: {
+            readonly type: "string";
+            readonly maxLength: 100;
+        };
+        readonly base_url: {
+            readonly type: "string";
+            readonly format: "uri";
+            readonly description: "Base URL of the API";
+        };
+        readonly type: {
+            readonly type: "string";
+            readonly enum: readonly SkillType[];
+            readonly default: "API";
+        };
+        readonly payment: {
+            readonly type: "object";
+            readonly required: readonly ["networks", "payTo"];
+            readonly properties: {
+                readonly networks: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                        readonly enum: readonly PaymentNetwork[];
+                    };
+                    readonly minItems: 1;
+                    readonly description: "Supported payment networks";
+                };
+                readonly asset: {
+                    readonly type: "string";
+                    readonly default: "USDC";
+                    readonly description: "Payment asset";
+                };
+                readonly payTo: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly description: "Recipient address (Stellar or EVM)";
+                };
+                readonly payToEvm: {
+                    readonly type: "string";
+                    readonly pattern: "^0x[a-fA-F0-9]{40}$";
+                    readonly description: "EVM address (fallback)";
+                };
+                readonly facilitator: {
+                    readonly type: "string";
+                    readonly format: "uri";
+                    readonly description: "Facilitator URL";
+                };
+            };
+            readonly additionalProperties: false;
+        };
+        readonly endpoints: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly required: readonly ["path", "method", "description", "priceUsdc"];
+                readonly properties: {
+                    readonly path: {
+                        readonly type: "string";
+                        readonly pattern: "^/";
+                        readonly description: "Endpoint path (must start with /)";
+                    };
+                    readonly method: {
+                        readonly type: "string";
+                        readonly enum: readonly HttpMethod[];
+                    };
+                    readonly description: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly priceUsdc: {
+                        readonly type: "string";
+                        readonly pattern: "^\\d+(\\.\\d+)?$";
+                        readonly description: "Price in USDC (e.g. \"0.001\")";
+                    };
+                    readonly inputSchema: {
+                        readonly type: "object";
+                        readonly description: "JSON Schema for request body";
+                    };
+                    readonly outputSchema: {
+                        readonly type: "object";
+                        readonly description: "JSON Schema for response body";
+                    };
+                };
+                readonly additionalProperties: false;
+            };
+            readonly minItems: 1;
+        };
+        readonly tags: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+            readonly maxItems: 20;
+        };
+        readonly category: {
+            readonly type: "string";
+        };
+        readonly sla: {
+            readonly type: "string";
+            readonly description: "Uptime guarantee (e.g. \"99.9%\")";
+        };
+        readonly rateLimit: {
+            readonly type: "string";
+            readonly description: "Rate limit (e.g. \"1000/hour\")";
+        };
+        readonly sandbox: {
+            readonly type: "string";
+            readonly format: "uri";
+            readonly description: "Free test endpoint URL";
+        };
+    };
+    readonly additionalProperties: true;
+};
+
+declare const SKILL_TYPES: readonly SkillType[];
+declare const HTTP_METHODS: readonly HttpMethod[];
+declare const PAYMENT_NETWORKS: readonly PaymentNetwork[];
+
+export { type EndpointSpec, HTTP_METHODS, type HttpMethod, type JSONSchema, type LegacyFrontmatter, type McpToolDefinition, type OpenAPIOperation, type OpenAPIPathItem, type OpenAPISpec, PAYMENT_NETWORKS, type PaymentConfig, type PaymentNetwork, SKILLMD_JSON_SCHEMA, SKILL_TYPES, type SkillConfig, type SkillManifest, type SkillType, type ValidationError, type ValidationResult, type ValidationWarning, generateFromOpenAPI, generateSkillMd, parseFrontmatter, parseSkillMd, toMcpToolDefinitions, toOpenAPI, validateSkill, validateSkillMd };