sharetribe-flex-build-sdk 1.15.0

package/README.md

@@ -0,0 +1,222 @@
+# Sharetribe Flex Build SDK
+
+SDK for building and managing Sharetribe Flex transaction processes programmatically.
+
+## Installation
+
+```bash
+npm install sharetribe-flex-build-sdk
+```
+
+## Features
+
+- **Process Management**: Programmatic API for all process commands (list, create, push, pull, aliases)
+- **API Client Functions**: Make authenticated API calls to Sharetribe Build API
+- **Transit Support**: Full support for Transit format encoding/decoding
+- **EDN Parser**: Parse and serialize process.edn files
+- **HTTP Client**: Pure Node.js HTTP client (no external dependencies except transit-js/jsedn)
+- **TypeScript**: Full type definitions included
+- **1-to-1 with CLI**: Functions match CLI command capabilities exactly
+
+## Quick Start
+
+The SDK provides programmatic access to all CLI capabilities:
+
+```typescript
+import {
+  listProcesses,
+  getProcess,
+  createProcess,
+  pushProcess,
+  createAlias
+} from 'sharetribe-flex-build-sdk';
+
+const apiKey = 'your-api-key';
+const marketplace = 'your-marketplace-id';
+
+// List all processes
+const processes = await listProcesses(apiKey, marketplace);
+
+// Get a specific process
+const process = await getProcess(apiKey, marketplace, 'my-process');
+
+// Create new process
+await createProcess(apiKey, marketplace, 'new-process', ednDefinition);
+
+// Push an update
+await pushProcess(apiKey, marketplace, 'my-process', updatedDefinition, templates);
+
+// Create alias
+await createAlias(apiKey, marketplace, 'my-process', 1, 'release');
+```
+
+## Usage
+
+### Process Management (CLI Equivalents)
+
+```typescript
+import {
+  listProcesses,
+  listProcessVersions,
+  getProcess,
+  createProcess,
+  pushProcess,
+  createAlias,
+  updateAlias,
+  deleteAlias
+} from 'sharetribe-flex-build-sdk';
+
+// List processes (flex-cli: process list)
+const processes = await listProcesses(apiKey, marketplace);
+// Returns: [{ name: 'instant-booking', version: 3 }, ...]
+
+// List versions (flex-cli: process list --process my-process)
+const versions = await listProcessVersions(apiKey, marketplace, 'my-process');
+// Returns: [{ version: 1, createdAt: '...', aliases: ['release'], transactionCount: 42 }, ...]
+
+// Get process details (flex-cli: process pull)
+const details = await getProcess(apiKey, marketplace, 'my-process', { version: '2' });
+// Returns: { definition: '...', version: 2, emailTemplates: [...] }
+
+// Create process (flex-cli: process create)
+const result = await createProcess(apiKey, marketplace, 'new-process', ednString);
+// Returns: { name: 'new-process', version: 1 }
+
+// Push update (flex-cli: process push)
+const pushResult = await pushProcess(apiKey, marketplace, 'my-process', ednString, templates);
+// Returns: { version: 2 } or { noChanges: true }
+
+// Manage aliases (flex-cli: process create-alias, update-alias)
+await createAlias(apiKey, marketplace, 'my-process', 1, 'release');
+await updateAlias(apiKey, marketplace, 'my-process', 2, 'release');
+await deleteAlias(apiKey, marketplace, 'my-process', 'release');
+```
+
+### Parse EDN Process Files
+
+```typescript
+import { parseProcessFile, serializeProcess } from 'sharetribe-flex-build-sdk';
+
+// Parse a process.edn file
+const process = parseProcessFile('./process.edn');
+console.log(process.name, process.states, process.transitions);
+
+// Serialize back to EDN format
+const ednString = serializeProcess(process);
+```
+
+### Make API Calls
+
+```typescript
+import { apiGet, apiPost, apiPostTransit } from 'sharetribe-flex-build-sdk';
+
+const apiKey = 'your-api-key';
+const marketplace = 'your-marketplace-id';
+
+// List processes
+const response = await apiGet(apiKey, '/processes/query', { marketplace });
+
+// Create a process
+await apiPost(apiKey, '/processes/create', { marketplace }, {
+  process: 'my-process-name'
+});
+
+// Push a process update (Transit format)
+await apiPostTransit(apiKey, '/processes/update',
+  { marketplace, process: 'my-process' },
+  processData
+);
+```
+
+### Transit Utilities
+
+```typescript
+import { encodeTransit, decodeTransit, keyword, keywordMap } from 'sharetribe-flex-build-sdk';
+
+// Create Transit keywords (Clojure-style)
+const processName = keyword('instant-booking');
+
+// Create Transit maps with keyword keys
+const transitMap = keywordMap({
+  name: keyword('my-process'),
+  version: 1
+});
+
+// Encode/decode Transit format
+const encoded = encodeTransit(transitMap);
+const decoded = decodeTransit(encoded);
+```
+
+### Type Definitions
+
+```typescript
+import type {
+  ProcessDefinition,
+  ProcessState,
+  ProcessTransition,
+  ProcessNotification,
+  ApiError,
+  HttpResponse
+} from 'sharetribe-flex-build-sdk';
+```
+
+## API Reference
+
+### API Functions
+
+- `apiGet(apiKey, endpoint, queryParams?)` - Make GET request
+- `apiPost(apiKey, endpoint, queryParams?, body?)` - Make POST request
+- `apiDelete(apiKey, endpoint, queryParams?)` - Make DELETE request
+- `apiPostMultipart(apiKey, endpoint, queryParams, fields)` - Make multipart POST
+- `apiPostTransit(apiKey, endpoint, queryParams, body)` - Make Transit-encoded POST
+
+### EDN Functions
+
+- `parseProcessFile(filePath)` - Parse process.edn file
+- `serializeProcess(process)` - Serialize to EDN format
+
+### Transit Functions
+
+- `encodeTransit(data)` - Encode to Transit JSON
+- `decodeTransit(transitString)` - Decode from Transit JSON
+- `keyword(name)` - Create Transit keyword
+- `keywordMap(obj)` - Create Transit map with keyword keys
+
+### HTTP Functions
+
+- `request(url, options)` - Low-level HTTP request
+- `get(url, headers?)` - HTTP GET
+- `post(url, data, headers?)` - HTTP POST with JSON
+- `postTransit(url, body, headers?)` - HTTP POST with Transit
+- `del(url, headers?)` - HTTP DELETE
+
+## CLI vs SDK
+
+The SDK provides programmatic access to CLI capabilities:
+
+| CLI Command | SDK Function |
+|-------------|--------------|
+| `process list` | `listProcesses()` |
+| `process list --process NAME` | `listProcessVersions()` |
+| `process pull` | `getProcess()` |
+| `process create` | `createProcess()` |
+| `process push` | `pushProcess()` |
+| `process create-alias` | `createAlias()` |
+| `process update-alias` | `updateAlias()` |
+| `process delete-alias` | `deleteAlias()` |
+
+**Note**: For v1.15.0, the SDK focuses on process management (the core functionality). The CLI includes additional commands (search, assets, notifications, listing-approval, stripe, events) which use the lower-level API client functions exported by this SDK. Future versions may add higher-level wrappers for these commands.
+
+## Related Packages
+
+- [sharetribe-cli](https://www.npmjs.com/package/sharetribe-cli) - Command-line interface (v1.15.0, depends on this SDK)
+
+## Version Relationship
+
+- CLI version 1.15.0 depends on SDK version 1.15.0 exactly
+- Both packages are maintained in the same [monorepo](https://github.com/jayenashar/sharetribe-cli)
+- Versions are kept in sync (1-to-1 relationship)
+
+## License
+
+Apache-2.0

package/build.js

@@ -0,0 +1,49 @@
+/**
+ * Build script for sharetribe-flex-build-sdk using esbuild
+ */
+
+import * as esbuild from 'esbuild';
+import { readFileSync } from 'node:fs';
+
+const pkg = JSON.parse(readFileSync('./package.json', 'utf-8'));
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+const isWatch = args.includes('--watch');
+const isDev = args.includes('--dev');
+
+const buildOptions = {
+  entryPoints: ['src/index.ts'],
+  bundle: true,
+  platform: 'node',
+  target: 'node18',
+  format: 'esm',
+  outfile: 'dist/index.js',
+  sourcemap: isDev,
+  minify: !isDev,
+  external: [
+    ...Object.keys(pkg.dependencies || {}),
+    ...Object.keys(pkg.peerDependencies || {}),
+  ],
+  banner: {
+    js: '#!/usr/bin/env node',
+  },
+};
+
+async function build() {
+  try {
+    if (isWatch) {
+      const ctx = await esbuild.context(buildOptions);
+      await ctx.watch();
+      console.log('Watching for changes...');
+    } else {
+      await esbuild.build(buildOptions);
+      console.log('Build complete!');
+    }
+  } catch (error) {
+    console.error('Build failed:', error);
+    process.exit(1);
+  }
+}
+
+build();

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "sharetribe-flex-build-sdk",
+  "version": "1.15.0",
+  "description": "SDK for building and managing Sharetribe Flex transaction processes",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/**/*.ts",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "sharetribe",
+    "flex",
+    "sdk",
+    "marketplace",
+    "transaction-process",
+    "build-api"
+  ],
+  "author": "",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jayenashar/sharetribe-flex-build-sdk"
+  },
+  "dependencies": {
+    "jsedn": "^0.4.1",
+    "transit-js": "^0.8.874"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.10",
+    "@typescript-eslint/eslint-plugin": "^8.18.2",
+    "@typescript-eslint/parser": "^8.18.2",
+    "eslint": "^9.17.0",
+    "prettier": "^3.4.2",
+    "typescript": "^5.7.2",
+    "vitest": "^4.0.16"
+  }
+}

package/src/api/client.ts

@@ -0,0 +1,218 @@
+/**
+ * Sharetribe API client
+ *
+ * Handles authentication and API requests to Sharetribe backend
+ */
+
+import { get, post, del, request, postTransit, HttpResponse } from './http-client.js';
+import { createMultipartBody, MultipartField } from './multipart.js';
+import { encodeTransit, decodeTransit } from './transit.js';
+import { readAuth } from '../auth-storage.js';
+
+// Re-export MultipartField for use in commands
+export type { MultipartField };
+
+// API base URL - must match flex-cli exactly
+const API_BASE_URL = 'https://flex-build-api.sharetribe.com/v1/build-api';
+
+export interface ApiError {
+  code: string;
+  message: string;
+  status: number;
+}
+
+/**
+ * Gets authentication headers from provided API key or auth file
+ *
+ * @param apiKey - Optional Sharetribe API key. If not provided, reads from ~/.config/flex-cli/auth.edn
+ * @returns Authorization headers
+ */
+function getAuthHeaders(apiKey?: string): Record<string, string> {
+  let key = apiKey;
+
+  if (!key) {
+    const auth = readAuth();
+    if (!auth) {
+      throw new Error('Not logged in. Please provide apiKey or run: sharetribe-cli login');
+    }
+    key = auth.apiKey;
+  }
+
+  return {
+    Authorization: `Apikey ${key}`,
+  };
+}
+
+/**
+ * Handles API response and errors
+ */
+function handleResponse<T>(response: HttpResponse): T {
+  if (response.statusCode >= 200 && response.statusCode < 300) {
+    if (response.body) {
+      return JSON.parse(response.body) as T;
+    }
+    return {} as T;
+  }
+
+  // Parse error response
+  let errorData: { errors?: Array<{ code: string; message?: string }> } = {};
+  try {
+    errorData = JSON.parse(response.body);
+  } catch {
+    // Ignore parse errors
+  }
+
+  const firstError = errorData.errors?.[0];
+  const error: ApiError = {
+    code: firstError?.code || 'UNKNOWN_ERROR',
+    message: firstError?.message || `HTTP ${response.statusCode}`,
+    status: response.statusCode,
+  };
+
+  throw error;
+}
+
+/**
+ * Makes a GET request to the API
+ *
+ * @param apiKey - Optional Sharetribe API key. If not provided, reads from ~/.config/flex-cli/auth.edn
+ * @param endpoint - API endpoint path
+ * @param queryParams - Optional query parameters
+ * @returns API response
+ */
+export async function apiGet<T>(apiKey: string | undefined, endpoint: string, queryParams?: Record<string, string>): Promise<T> {
+  const url = new URL(API_BASE_URL + endpoint);
+  if (queryParams) {
+    Object.entries(queryParams).forEach(([key, value]) => {
+      url.searchParams.append(key, value);
+    });
+  }
+
+  const response = await get(url.toString(), getAuthHeaders(apiKey));
+  return handleResponse<T>(response);
+}
+
+/**
+ * Makes a POST request to the API
+ *
+ * @param apiKey - Optional Sharetribe API key. If not provided, reads from ~/.config/flex-cli/auth.edn
+ * @param endpoint - API endpoint path
+ * @param queryParams - Optional query parameters
+ * @param body - Request body
+ * @returns API response
+ */
+export async function apiPost<T>(
+  apiKey: string | undefined,
+  endpoint: string,
+  queryParams?: Record<string, string>,
+  body?: unknown
+): Promise<T> {
+  const url = new URL(API_BASE_URL + endpoint);
+  if (queryParams) {
+    Object.entries(queryParams).forEach(([key, value]) => {
+      url.searchParams.append(key, value);
+    });
+  }
+
+  const response = await post(url.toString(), body, getAuthHeaders(apiKey));
+  return handleResponse<T>(response);
+}
+
+/**
+ * Makes a DELETE request to the API
+ *
+ * @param apiKey - Optional Sharetribe API key. If not provided, reads from ~/.config/flex-cli/auth.edn
+ * @param endpoint - API endpoint path
+ * @param queryParams - Optional query parameters
+ * @returns API response
+ */
+export async function apiDelete<T>(
+  apiKey: string | undefined,
+  endpoint: string,
+  queryParams?: Record<string, string>
+): Promise<T> {
+  const url = new URL(API_BASE_URL + endpoint);
+  if (queryParams) {
+    Object.entries(queryParams).forEach(([key, value]) => {
+      url.searchParams.append(key, value);
+    });
+  }
+
+  const response = await del(url.toString(), getAuthHeaders(apiKey));
+  return handleResponse<T>(response);
+}
+
+/**
+ * Makes a multipart form-data POST request to the API
+ *
+ * @param apiKey - Optional Sharetribe API key. If not provided, reads from ~/.config/flex-cli/auth.edn
+ * @param endpoint - API endpoint path
+ * @param queryParams - Query parameters
+ * @param fields - Multipart form fields
+ * @returns API response
+ */
+export async function apiPostMultipart<T>(
+  apiKey: string | undefined,
+  endpoint: string,
+  queryParams: Record<string, string>,
+  fields: MultipartField[]
+): Promise<T> {
+  const url = new URL(API_BASE_URL + endpoint);
+  Object.entries(queryParams).forEach(([key, value]) => {
+    url.searchParams.append(key, value);
+  });
+
+  const { body, contentType } = createMultipartBody(fields);
+
+  const headers = {
+    ...getAuthHeaders(apiKey),
+    'Content-Type': contentType,
+    'Content-Length': body.length.toString(),
+  };
+
+  const response = await request(url.toString(), {
+    method: 'POST',
+    headers,
+    body,
+  });
+  return handleResponse<T>(response);
+}
+
+/**
+ * Makes a POST request to the API with Transit-encoded body
+ * Transit is a data format used by the Sharetribe API for certain endpoints
+ *
+ * @param apiKey - Optional Sharetribe API key. If not provided, reads from ~/.config/flex-cli/auth.edn
+ * @param endpoint - API endpoint path
+ * @param queryParams - Query parameters
+ * @param body - Request body (will be Transit-encoded)
+ * @returns API response
+ */
+export async function apiPostTransit<T>(
+  apiKey: string | undefined,
+  endpoint: string,
+  queryParams: Record<string, string>,
+  body: unknown
+): Promise<T> {
+  const url = new URL(API_BASE_URL + endpoint);
+  Object.entries(queryParams).forEach(([key, value]) => {
+    url.searchParams.append(key, value);
+  });
+
+  const transitBody = encodeTransit(body);
+  const response = await postTransit(url.toString(), transitBody, getAuthHeaders(apiKey));
+
+  // Parse Transit response
+  if (response.statusCode >= 400) {
+    const errorData = decodeTransit(response.body) as any;
+    const firstError = errorData.errors?.[0];
+    const error: ApiError = {
+      code: firstError?.code || 'UNKNOWN_ERROR',
+      message: firstError?.title || `HTTP ${response.statusCode}`,
+      status: response.statusCode,
+    };
+    throw error;
+  }
+
+  return decodeTransit(response.body) as T;
+}

package/src/api/http-client.ts

@@ -0,0 +1,135 @@
+/**
+ * HTTP client using Node.js built-in http/https modules
+ *
+ * No external dependencies - pure Node.js implementation
+ */
+
+import * as https from 'node:https';
+import * as http from 'node:http';
+import { URL } from 'node:url';
+
+export interface HttpOptions {
+  method?: string;
+  headers?: Record<string, string>;
+  body?: string | Buffer;
+  timeout?: number;
+}
+
+export interface HttpResponse {
+  statusCode: number;
+  headers: http.IncomingHttpHeaders;
+  body: string;
+}
+
+/**
+ * Makes an HTTP/HTTPS request using Node.js built-in modules
+ *
+ * Returns a promise that resolves with the response
+ */
+export function request(url: string, options: HttpOptions = {}): Promise<HttpResponse> {
+  return new Promise((resolve, reject) => {
+    const parsedUrl = new URL(url);
+    const isHttps = parsedUrl.protocol === 'https:';
+    const client = isHttps ? https : http;
+
+    const requestOptions: http.RequestOptions = {
+      hostname: parsedUrl.hostname,
+      port: parsedUrl.port || (isHttps ? 443 : 80),
+      path: parsedUrl.pathname + parsedUrl.search,
+      method: options.method || 'GET',
+      headers: options.headers || {},
+      timeout: options.timeout || 30000,
+    };
+
+    const req = client.request(requestOptions, (res) => {
+      const chunks: Buffer[] = [];
+
+      res.on('data', (chunk: Buffer) => {
+        chunks.push(chunk);
+      });
+
+      res.on('end', () => {
+        const body = Buffer.concat(chunks).toString('utf-8');
+        resolve({
+          statusCode: res.statusCode || 0,
+          headers: res.headers,
+          body,
+        });
+      });
+    });
+
+    req.on('error', (error) => {
+      reject(error);
+    });
+
+    req.on('timeout', () => {
+      req.destroy();
+      reject(new Error('Request timeout'));
+    });
+
+    if (options.body) {
+      req.write(options.body);
+    }
+
+    req.end();
+  });
+}
+
+/**
+ * Makes a GET request
+ */
+export function get(url: string, headers?: Record<string, string>): Promise<HttpResponse> {
+  return request(url, { method: 'GET', headers });
+}
+
+/**
+ * Makes a POST request with JSON body
+ */
+export function post(
+  url: string,
+  data: unknown,
+  headers?: Record<string, string>
+): Promise<HttpResponse> {
+  const body = JSON.stringify(data);
+  const allHeaders = {
+    'Content-Type': 'application/json',
+    'Content-Length': Buffer.byteLength(body).toString(),
+    ...headers,
+  };
+
+  return request(url, {
+    method: 'POST',
+    headers: allHeaders,
+    body,
+  });
+}
+
+/**
+ * Makes a POST request with Transit body
+ * Transit is a data format used by the Sharetribe API for certain endpoints
+ */
+export function postTransit(
+  url: string,
+  body: string,
+  headers?: Record<string, string>
+): Promise<HttpResponse> {
+  const allHeaders = {
+    'Content-Type': 'application/transit+json',
+    'Accept': 'application/transit+json',
+    'Content-Length': Buffer.byteLength(body).toString(),
+    ...headers,
+  };
+
+  return request(url, {
+    method: 'POST',
+    headers: allHeaders,
+    body,
+  });
+}
+
+/**
+ * Makes a DELETE request
+ */
+export function del(url: string, headers?: Record<string, string>): Promise<HttpResponse> {
+  return request(url, { method: 'DELETE', headers });
+}