sharetribe-flex-build-sdk 1.15.0

package/src/api/multipart.ts

@@ -0,0 +1,78 @@
+/**
+ * Multipart form-data implementation using Node.js streams
+ *
+ * No external dependencies - implements multipart/form-data manually
+ */
+
+import { randomBytes } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+
+export interface MultipartField {
+  name: string;
+  value: string | Buffer;
+  filename?: string;
+  contentType?: string;
+}
+
+/**
+ * Generates a random boundary for multipart form-data
+ * Returns the boundary without the -- prefix (that gets added when building the body)
+ */
+function generateBoundary(): string {
+  return `WebKitFormBoundary${randomBytes(16).toString('hex')}`;
+}
+
+/**
+ * Creates multipart form-data body from fields
+ */
+export function createMultipartBody(fields: MultipartField[]): {
+  body: Buffer;
+  boundary: string;
+  contentType: string;
+} {
+  const boundary = generateBoundary();
+  const parts: Buffer[] = [];
+
+  for (const field of fields) {
+    // Add boundary
+    parts.push(Buffer.from(`--${boundary}\r\n`));
+
+    // Add Content-Disposition header
+    if (field.filename) {
+      parts.push(
+        Buffer.from(
+          `Content-Disposition: form-data; name="${field.name}"; filename="${field.filename}"\r\n`
+        )
+      );
+
+      // Add Content-Type if specified
+      if (field.contentType) {
+        parts.push(Buffer.from(`Content-Type: ${field.contentType}\r\n`));
+      }
+    } else {
+      parts.push(Buffer.from(`Content-Disposition: form-data; name="${field.name}"\r\n`));
+    }
+
+    parts.push(Buffer.from('\r\n'));
+
+    // Add value
+    if (typeof field.value === 'string') {
+      parts.push(Buffer.from(field.value));
+    } else {
+      parts.push(field.value);
+    }
+
+    parts.push(Buffer.from('\r\n'));
+  }
+
+  // Add final boundary
+  parts.push(Buffer.from(`--${boundary}--\r\n`));
+
+  const body = Buffer.concat(parts);
+
+  return {
+    body,
+    boundary,
+    contentType: `multipart/form-data; boundary=${boundary}`,
+  };
+}

package/src/api/transit.ts

@@ -0,0 +1,96 @@
+/**
+ * Transit format encoding/decoding for Sharetribe API
+ *
+ * The Build API expects Transit format (application/transit+json) for certain endpoints.
+ * Transit is a data format that extends JSON with support for additional data types.
+ */
+
+import transit from 'transit-js';
+
+/**
+ * Encodes data to Transit JSON format
+ *
+ * @param data - The data to encode (can include keywords, dates, etc.)
+ * @returns Transit-encoded string
+ */
+export function encodeTransit(data: unknown): string {
+  const writer = transit.writer('json', {
+    handlers: transit.map([
+      // Add any custom handlers here if needed
+    ])
+  });
+  return writer.write(data);
+}
+
+/**
+ * Converts Transit values (maps, keywords, etc.) to plain JavaScript objects
+ *
+ * @param val - Transit value
+ * @returns Plain JavaScript value
+ */
+function transitToJS(val: any): any {
+  // Handle Transit maps
+  if (val && typeof val.get === 'function' && val._entries) {
+    const obj: Record<string, any> = {};
+    for (let i = 0; i < val._entries.length; i += 2) {
+      const key = val._entries[i];
+      const value = val._entries[i + 1];
+      // Convert keyword keys to strings (e.g., :data -> "data")
+      const keyStr = key._name || String(key);
+      obj[keyStr] = transitToJS(value);
+    }
+    return obj;
+  }
+
+  // Handle Transit keywords
+  if (val && val._name !== undefined) {
+    return val._name;
+  }
+
+  // Handle arrays
+  if (Array.isArray(val)) {
+    return val.map(transitToJS);
+  }
+
+  // Return primitives as-is
+  return val;
+}
+
+/**
+ * Decodes Transit JSON format to JavaScript objects
+ *
+ * @param transitString - Transit-encoded string
+ * @returns Decoded JavaScript object
+ */
+export function decodeTransit(transitString: string): unknown {
+  const reader = transit.reader('json');
+  const transitValue = reader.read(transitString);
+  return transitToJS(transitValue);
+}
+
+/**
+ * Creates a Transit keyword (used for Clojure-style keywords in the API)
+ *
+ * @param name - The keyword name (e.g., "default-booking")
+ * @returns Transit keyword object
+ */
+export function keyword(name: string): unknown {
+  return transit.keyword(name);
+}
+
+/**
+ * Creates a Transit map with keyword keys
+ *
+ * This is needed because the Sharetribe API expects Transit maps with keyword keys,
+ * not string keys. In Clojure/Transit: {:name :value} not {"name" :value}
+ *
+ * @param obj - Plain JavaScript object with string keys
+ * @returns Transit map with keyword keys
+ */
+export function keywordMap(obj: Record<string, unknown>): unknown {
+  const entries: unknown[] = [];
+  for (const [key, value] of Object.entries(obj)) {
+    entries.push(transit.keyword(key), value);
+  }
+  return transit.map(entries);
+}

package/src/assets.ts

@@ -0,0 +1,116 @@
+/**
+ * Asset management functions
+ *
+ * Programmatic API for managing marketplace assets
+ */
+
+import { apiGet, apiPostMultipart, type MultipartField } from './api/client.js';
+
+export interface Asset {
+  path: string;
+  dataRaw: string; // base64 encoded
+  contentHash?: string;
+}
+
+export interface PullAssetsResult {
+  version: string;
+  assets: Asset[];
+}
+
+export interface PushAssetsResult {
+  version: string;
+  assets: Array<{ path: string; contentHash: string }>;
+}
+
+/**
+ * Pulls assets from remote
+ *
+ * @param apiKey - Sharetribe API key (optional, reads from auth file if not provided)
+ * @param marketplace - Marketplace ID
+ * @param options - Pull options
+ * @returns Assets and version information
+ */
+export async function pullAssets(
+  apiKey: string | undefined,
+  marketplace: string,
+  options?: { version?: string }
+): Promise<PullAssetsResult> {
+  const params: Record<string, string> = { marketplace };
+
+  if (options?.version) {
+    params.version = options.version;
+  } else {
+    params['version-alias'] = 'latest';
+  }
+
+  const response = await apiGet<{
+    data: Array<{
+      path: string;
+      'data-raw': string;
+      'content-hash'?: string;
+    }>;
+    meta: { version?: string; 'aliased-version'?: string };
+  }>(apiKey, '/assets/pull', params);
+
+  const version = response.meta.version || response.meta['aliased-version'];
+  if (!version) {
+    throw new Error('No version information in response');
+  }
+
+  return {
+    version,
+    assets: response.data.map(a => ({
+      path: a.path,
+      dataRaw: a['data-raw'],
+      contentHash: a['content-hash'],
+    })),
+  };
+}
+
+/**
+ * Pushes assets to remote
+ *
+ * @param apiKey - Sharetribe API key (optional, reads from auth file if not provided)
+ * @param marketplace - Marketplace ID
+ * @param currentVersion - Current version (use 'nil' if first push)
+ * @param operations - Array of operations to perform
+ * @returns New version and asset metadata
+ */
+export async function pushAssets(
+  apiKey: string | undefined,
+  marketplace: string,
+  currentVersion: string,
+  operations: Array<{
+    path: string;
+    op: 'upsert' | 'delete';
+    data?: Buffer;
+  }>
+): Promise<PushAssetsResult> {
+  const fields: MultipartField[] = [
+    { name: 'current-version', value: currentVersion },
+  ];
+
+  for (let i = 0; i < operations.length; i++) {
+    const op = operations[i];
+    fields.push({ name: `path-${i}`, value: op.path });
+    fields.push({ name: `op-${i}`, value: op.op });
+    if (op.op === 'upsert' && op.data) {
+      fields.push({ name: `data-raw-${i}`, value: op.data });
+    }
+  }
+
+  const response = await apiPostMultipart<{
+    data: {
+      version: string;
+      'asset-meta': { assets: Array<{ path: string; 'content-hash': string }> };
+    };
+  }>(apiKey, '/assets/push', { marketplace }, fields);
+
+  return {
+    version: response.data.version,
+    assets: response.data['asset-meta'].assets.map(a => ({
+      path: a.path,
+      contentHash: a['content-hash'],
+    })),
+  };
+}

package/src/auth-storage.ts

@@ -0,0 +1,77 @@
+/**
+ * Authentication storage - manages ~/.config/flex-cli/auth.edn
+ *
+ * Must maintain 100% compatibility with flex-cli's auth.edn format
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import edn from 'jsedn';
+
+const CONFIG_DIR = join(homedir(), '.config', 'flex-cli');
+const AUTH_FILE = join(CONFIG_DIR, 'auth.edn');
+
+export interface AuthData {
+  apiKey: string;
+}
+
+/**
+ * Reads authentication data from ~/.config/flex-cli/auth.edn
+ *
+ * Returns null if file doesn't exist or is invalid
+ */
+export function readAuth(): AuthData | null {
+  try {
+    if (!existsSync(AUTH_FILE)) {
+      return null;
+    }
+
+    const content = readFileSync(AUTH_FILE, 'utf-8');
+    const parsed = edn.parse(content);
+
+    // EDN keys are symbols, get :api-key
+    const apiKeySymbol = edn.kw(':api-key');
+    const apiKey = parsed.at(apiKeySymbol);
+
+    if (typeof apiKey !== 'string') {
+      return null;
+    }
+
+    return { apiKey };
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Writes authentication data to ~/.config/flex-cli/auth.edn
+ *
+ * Format must match flex-cli exactly: {:api-key "..."}
+ */
+export function writeAuth(data: AuthData): void {
+  // Ensure config directory exists
+  if (!existsSync(CONFIG_DIR)) {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+  }
+
+  // Create EDN map with :api-key
+  const authMap = new (edn as any).Map([edn.kw(':api-key'), data.apiKey]);
+  const ednString = edn.encode(authMap);
+
+  writeFileSync(AUTH_FILE, ednString, 'utf-8');
+}
+
+/**
+ * Clears authentication data (deletes auth.edn file)
+ */
+export async function clearAuth(): Promise<void> {
+  try {
+    if (existsSync(AUTH_FILE)) {
+      const fs = await import('node:fs/promises');
+      await fs.unlink(AUTH_FILE);
+    }
+  } catch (error) {
+    // Ignore errors if file doesn't exist
+  }
+}

package/src/deploy.ts

@@ -0,0 +1,96 @@
+/**
+ * Process deployment functions
+ *
+ * High-level functions for deploying processes to aliases
+ */
+
+import { createProcess, pushProcess, createAlias, updateAlias } from './processes.js';
+import { serializeProcess } from './edn-process.js';
+import type { ProcessDefinition } from './types.js';
+
+export interface DeployProcessOptions {
+  /** Process name */
+  process: string;
+  /** Target alias to deploy to */
+  alias: string;
+  /** Path to process.edn file (used for display only) */
+  path?: string;
+  /** Process definition to deploy */
+  processDefinition: ProcessDefinition;
+}
+
+export interface DeployProcessResult {
+  /** Whether a new process was created */
+  processCreated: boolean;
+  /** Process version number */
+  version: number;
+  /** Whether a new alias was created */
+  aliasCreated: boolean;
+  /** Alias name */
+  alias: string;
+}
+
+/**
+ * Deploys a process to an alias
+ *
+ * This high-level function handles the complete deployment workflow:
+ * 1. Creates the process if it doesn't exist
+ * 2. Pushes the process definition to create a new version
+ * 3. Creates or updates the alias to point to the new version
+ *
+ * @param apiKey - Sharetribe API key (optional, reads from auth file if not provided)
+ * @param marketplace - Marketplace ID
+ * @param options - Deployment options
+ * @returns Deployment result including version and alias information
+ */
+export async function deployProcess(
+  apiKey: string | undefined,
+  marketplace: string,
+  options: DeployProcessOptions
+): Promise<DeployProcessResult> {
+  const { process, alias, processDefinition } = options;
+
+  // Serialize process definition to EDN format
+  const processEdn = serializeProcess(processDefinition);
+
+  // Step 1: Try to create the process (will fail if it already exists, which is fine)
+  let processCreated = false;
+  try {
+    await createProcess(apiKey, marketplace, process, processEdn);
+    processCreated = true;
+  } catch (error: any) {
+    // If process already exists, continue
+    if (error.code !== 'already-exists') {
+      throw error;
+    }
+  }
+
+  // Step 2: Push the process to create a new version
+  const pushResult = await pushProcess(apiKey, marketplace, process, processEdn);
+
+  // Ensure we have a version number
+  if (pushResult.version === undefined) {
+    throw new Error('Failed to get version number from push result');
+  }
+
+  // Step 3: Create or update the alias
+  let aliasCreated = false;
+  try {
+    await createAlias(apiKey, marketplace, process, pushResult.version, alias);
+    aliasCreated = true;
+  } catch (error: any) {
+    // If alias already exists, update it
+    if (error.code === 'already-exists') {
+      await updateAlias(apiKey, marketplace, process, pushResult.version, alias);
+    } else {
+      throw error;
+    }
+  }
+
+  return {
+    processCreated,
+    version: pushResult.version,
+    aliasCreated,
+    alias,
+  };
+}

package/src/edn-process.ts

@@ -0,0 +1,126 @@
+/**
+ * Process.edn file parser
+ *
+ * Parses transaction process definitions from EDN format
+ */
+
+import edn from 'jsedn';
+import { readFileSync } from 'node:fs';
+
+export interface ProcessState {
+  name: string;
+  in: string[];
+  out: string[];
+}
+
+export interface ProcessTransition {
+  name: string;
+  from: string;
+  to: string;
+  actor: string;
+  privileged?: boolean;
+  actions?: Array<{ name: string; config?: unknown }>;
+}
+
+export interface ProcessNotification {
+  name: string;
+  on: string;
+  to: string;
+  template: string;
+}
+
+export interface ProcessDefinition {
+  name: string;
+  version?: number;
+  states: ProcessState[];
+  transitions: ProcessTransition[];
+  notifications: ProcessNotification[];
+}
+
+/**
+ * Converts EDN keyword to string
+ */
+function ednKeywordToString(kw: unknown): string {
+  if (kw && typeof kw === 'object' && 'name' in kw) {
+    return (kw as { name: string }).name;
+  }
+  return String(kw);
+}
+
+/**
+ * Parses a process.edn file
+ */
+export function parseProcessFile(filePath: string): ProcessDefinition {
+  const content = readFileSync(filePath, 'utf-8');
+  const parsed = edn.parse(content);
+
+  // Extract process data from EDN map
+  const nameKw = edn.kw(':name');
+  const statesKw = edn.kw(':states');
+  const transitionsKw = edn.kw(':transitions');
+  const notificationsKw = edn.kw(':notifications');
+
+  const name = ednKeywordToString(parsed.at(nameKw));
+  const statesData = parsed.at(statesKw) || [];
+  const transitionsData = parsed.at(transitionsKw) || [];
+  const notificationsData = parsed.at(notificationsKw) || [];
+
+  // Parse states
+  const states: ProcessState[] = [];
+  if (Array.isArray(statesData)) {
+    for (const state of statesData) {
+      states.push({
+        name: ednKeywordToString(state.at(edn.kw(':name'))),
+        in: (state.at(edn.kw(':in')) || []).map(ednKeywordToString),
+        out: (state.at(edn.kw(':out')) || []).map(ednKeywordToString),
+      });
+    }
+  }
+
+  // Parse transitions
+  const transitions: ProcessTransition[] = [];
+  if (Array.isArray(transitionsData)) {
+    for (const transition of transitionsData) {
+      transitions.push({
+        name: ednKeywordToString(transition.at(edn.kw(':name'))),
+        from: ednKeywordToString(transition.at(edn.kw(':from'))),
+        to: ednKeywordToString(transition.at(edn.kw(':to'))),
+        actor: ednKeywordToString(transition.at(edn.kw(':actor'))),
+        privileged: transition.at(edn.kw(':privileged?')) || false,
+        actions: transition.at(edn.kw(':actions')) || [],
+      });
+    }
+  }
+
+  // Parse notifications
+  const notifications: ProcessNotification[] = [];
+  if (Array.isArray(notificationsData)) {
+    for (const notification of notificationsData) {
+      notifications.push({
+        name: ednKeywordToString(notification.at(edn.kw(':name'))),
+        on: ednKeywordToString(notification.at(edn.kw(':on'))),
+        to: ednKeywordToString(notification.at(edn.kw(':to'))),
+        template: ednKeywordToString(notification.at(edn.kw(':template'))),
+      });
+    }
+  }
+
+  return {
+    name,
+    states,
+    transitions,
+    notifications,
+  };
+}
+
+/**
+ * Serializes a process definition to EDN format
+ */
+export function serializeProcess(process: ProcessDefinition): string {
+  // For now, return a simplified EDN representation
+  // A full implementation would properly serialize to EDN format
+  return `{:name :${process.name}
+ :states [${process.states.map((s) => `{:name :${s.name} :in [${s.in.map((i) => `:${i}`).join(' ')}] :out [${s.out.map((o) => `:${o}`).join(' ')}]}`).join('\n          ')}]
+ :transitions [${process.transitions.map((t) => `{:name :${t.name} :from :${t.from} :to :${t.to} :actor :${t.actor}}`).join('\n               ')}]
+ :notifications [${process.notifications.map((n) => `{:name :${n.name} :on :${n.on} :to :${n.to} :template :${n.template}}`).join('\n                 ')}]}`;
+}