@aigne/afs-mapping 1.11.0-beta.6

package/LICENSE.md

@@ -0,0 +1,26 @@
+# Proprietary License
+
+Copyright (c) 2024-2025 ArcBlock, Inc. All Rights Reserved.
+
+This software and associated documentation files (the "Software") are proprietary
+and confidential. Unauthorized copying, modification, distribution, or use of
+this Software, via any medium, is strictly prohibited.
+
+The Software is provided for internal use only within ArcBlock, Inc. and its
+authorized affiliates.
+
+## No License Granted
+
+No license, express or implied, is granted to any party for any purpose.
+All rights are reserved by ArcBlock, Inc.
+
+## Public Artifact Distribution
+
+Portions of this Software may be released publicly under separate open-source
+licenses (such as MIT License) through designated public repositories. Such
+public releases are governed by their respective licenses and do not affect
+the proprietary nature of this repository.
+
+## Contact
+
+For licensing inquiries, contact: legal@arcblock.io

package/README.md

@@ -0,0 +1,286 @@
+# @aigne/afs-mapping
+
+**@aigne/afs-mapping** is a DSL compiler for declarative path-to-API mapping. It converts YAML DSL definitions into compiled route matchers, enabling AFS providers to map virtual paths to external API calls.
+
+## Overview
+
+AFS Mapping provides the infrastructure for building AFS providers that interact with external APIs. It allows you to declaratively define how AFS paths map to API endpoints, how parameters are extracted and bound, and how API responses are transformed into AFS entries.
+
+## Features
+
+- **YAML DSL**: Declarative mapping configuration in YAML format
+- **Path Resolution**: Pattern-based route matching with parameter extraction
+- **Expression Binding**: Flexible parameter binding with Jinja-like expressions
+- **Response Projection**: Transform API responses into AFS entries
+- **Multi-Operation Support**: Define list, read, write, create, and delete operations
+- **Modular Configuration**: Split mappings across multiple files with includes
+
+## Installation
+
+```bash
+npm install @aigne/afs-mapping
+# or
+yarn add @aigne/afs-mapping
+# or
+pnpm add @aigne/afs-mapping
+```
+
+## Quick Start
+
+```typescript
+import { MappingCompiler } from "@aigne/afs-mapping";
+
+// Compile a mapping configuration
+const compiler = new MappingCompiler();
+const compiled = await compiler.compileDirectory("/path/to/mapping/");
+
+// Resolve a path to route information
+const resolved = compiled.resolve("/aigne/afs/issues/123");
+// => { template: "/{owner}/{repo}/issues/{number}", params: { owner: "aigne", repo: "afs", number: "123" }, ... }
+
+// Build an HTTP request
+const request = compiled.buildRequest("/aigne/afs/issues", "list", {
+  query: { state: "open" },
+});
+// => { method: "GET", path: "/repos/aigne/afs/issues", params: { state: "open", per_page: 30 }, ... }
+
+// Project API response to AFS entries
+const entries = compiled.projectResponse("/aigne/afs/issues", "list", apiResponse);
+```
+
+## Mapping DSL
+
+### Configuration Structure
+
+```yaml
+# mapping.yml
+name: github
+version: "1.0"
+description: GitHub API mapping
+
+defaults:
+  baseUrl: https://api.github.com
+  headers:
+    Accept: application/vnd.github+json
+
+routes:
+  "/{owner}/{repo}/issues":
+    list:
+      method: GET
+      path: /repos/{owner}/{repo}/issues
+      params:
+        owner: path.owner
+        repo: path.repo
+        state: query.state | default("open")
+        per_page: query.limit | default(30)
+      transform:
+        items: "$"
+        entry:
+          id: "$.number | string"
+          path: "/{owner}/{repo}/issues/{$.number}"
+          summary: "$.title"
+          content: "$.body"
+```
+
+### Route Definition
+
+Each route defines operations for a path pattern:
+
+```yaml
+routes:
+  "/{owner}/{repo}/issues/{number}":
+    read:
+      method: GET
+      path: /repos/{owner}/{repo}/issues/{number}
+      params:
+        owner: path.owner
+        repo: path.repo
+        number: path.number
+      transform:
+        entry:
+          id: "$.number | string"
+          path: "/{owner}/{repo}/issues/{$.number}"
+          summary: "$.title"
+          content: "$.body"
+          metadata:
+            type: issue
+            state: "$.state"
+            author: "$.user.login"
+```
+
+### Operations
+
+Each route can define these operations:
+
+- **list**: Returns multiple entries (GET)
+- **read**: Returns a single entry (GET)
+- **write**: Updates an existing entry (PUT/PATCH)
+- **create**: Creates a new entry (POST)
+- **delete**: Removes an entry (DELETE)
+
+### Parameter Binding
+
+Parameters can be bound from various sources:
+
+```yaml
+params:
+  # From path parameters
+  owner: path.owner
+
+  # From query parameters with default
+  state: query.state | default("open")
+
+  # From request input
+  title: input.title
+
+  # Static values
+  per_page: "30"
+```
+
+### Response Transform
+
+Transform API responses into AFS entries:
+
+```yaml
+transform:
+  # JSONPath to items array (for list operations)
+  items: "$.data"
+
+  # Entry mapping
+  entry:
+    id: "$.id | string"
+    path: "/items/{$.id}"
+    summary: "$.title"
+    content: "$.body"
+    description: "$.description"
+    metadata:
+      type: "$.type"
+      status: "$.status"
+```
+
+## API Reference
+
+### MappingCompiler
+
+```typescript
+const compiler = new MappingCompiler();
+
+// Compile from a single file
+const compiled = await compiler.compileFile("/path/to/mapping.yml");
+
+// Compile from a directory (with includes)
+const compiled = await compiler.compileDirectory("/path/to/mapping/");
+
+// Compile from a config object (for testing)
+const compiled = compiler.compileConfig(configObject);
+```
+
+### CompiledMapping
+
+```typescript
+// Get mapping info
+compiled.name;        // Mapping name
+compiled.version;     // Version string
+compiled.routeCount;  // Number of routes
+compiled.operationCount; // Total operations
+
+// Resolve a path
+const resolved = compiled.resolve("/owner/repo/issues/123");
+// Returns: { template, params, operations }
+
+// Build HTTP request
+const request = compiled.buildRequest(path, operationType, { query, input });
+// Returns: { method, path, params, headers, body }
+
+// Project API response
+const entries = compiled.projectResponse(path, operationType, apiResponse);
+// Returns: AFSEntry[]
+```
+
+### ResolvedRoute
+
+```typescript
+interface ResolvedRoute {
+  template: string;                    // Original template
+  params: Record<string, string>;      // Extracted parameters
+  operations: {                        // Available operations
+    list?: Operation;
+    read?: Operation;
+    write?: Operation;
+    create?: Operation;
+    delete?: Operation;
+  };
+}
+```
+
+### HttpRequest
+
+```typescript
+interface HttpRequest {
+  method: string;                      // HTTP method
+  path: string;                        // Request path (interpolated)
+  params: Record<string, unknown>;     // Query/path parameters
+  headers?: Record<string, string>;    // Request headers
+  body?: Record<string, unknown>;      // Request body
+}
+```
+
+## Creating a Provider with Mapping
+
+Here's how to use AFS Mapping in a custom provider:
+
+```typescript
+import { AFSModule, AFSEntry } from "@aigne/afs";
+import { MappingCompiler, CompiledMapping } from "@aigne/afs-mapping";
+
+class MyAPIProvider implements AFSModule {
+  readonly name = "my-api";
+  private compiled: CompiledMapping;
+
+  constructor() {
+    const compiler = new MappingCompiler();
+    this.compiled = compiler.compileConfig({
+      name: "my-api",
+      version: "1.0",
+      routes: {
+        "/items": {
+          list: {
+            method: "GET",
+            path: "/api/items",
+            transform: {
+              items: "$",
+              entry: {
+                id: "$.id",
+                path: "/items/{$.id}",
+                summary: "$.name",
+              },
+            },
+          },
+        },
+      },
+    });
+  }
+
+  async list(path: string): Promise<{ data: AFSEntry[] }> {
+    const request = this.compiled.buildRequest(path, "list", {});
+    if (!request) return { data: [] };
+
+    // Make API call
+    const response = await fetch(`https://api.example.com${request.path}`);
+    const data = await response.json();
+
+    // Transform response
+    const entries = this.compiled.projectResponse(path, "list", data);
+    return { data: entries };
+  }
+}
+```
+
+## Related Packages
+
+- [@aigne/afs](../core/README.md) - AFS core package
+- [@aigne/afs-github](../../providers/github/README.md) - GitHub provider (uses AFS Mapping)
+
+## TypeScript Support
+
+This package includes full TypeScript type definitions.