sharetribe-flex-build-sdk 1.15.0

package/src/processes.ts

@@ -0,0 +1,320 @@
+/**
+ * Process management functions
+ *
+ * Programmatic API for managing Sharetribe transaction processes
+ */
+
+import { apiGet, apiPost, apiPostMultipart, apiPostTransit, type MultipartField } from './api/client.js';
+import { keyword, keywordMap } from './api/transit.js';
+
+export interface ProcessListItem {
+  name: string;
+  version?: number;
+}
+
+export interface ProcessVersion {
+  createdAt: string;
+  version: number;
+  aliases?: string[];
+  transactionCount?: number;
+}
+
+export interface ProcessDetails {
+  definition: string;
+  version: number;
+  name: string;
+  emailTemplates?: Array<{
+    name: string;
+    html: string;
+    subject: string;
+  }>;
+}
+
+export interface CreateProcessResult {
+  name: string;
+  version: number;
+}
+
+export interface PushProcessResult {
+  version?: number;
+  noChanges?: boolean;
+}
+
+export interface AliasResult {
+  alias: string;
+  version: number;
+}
+
+/**
+ * Lists all processes for a marketplace
+ *
+ * @param apiKey - Optional Sharetribe API key. If not provided, reads from ~/.config/flex-cli/auth.edn
+ * @param marketplace - Marketplace ID
+ * @returns Array of processes with their latest versions
+ */
+export async function listProcesses(
+  apiKey: string | undefined,
+  marketplace: string
+): Promise<ProcessListItem[]> {
+  const response = await apiGet<{ data: Array<{ 'process/name': string; 'process/version'?: number }> }>(
+    apiKey,
+    '/processes/query',
+    { marketplace }
+  );
+
+  return response.data.map(p => ({
+    name: p['process/name'],
+    version: p['process/version'],
+  }));
+}
+
+/**
+ * Lists all versions of a specific process
+ *
+ * @param apiKey - Sharetribe API key
+ * @param marketplace - Marketplace ID
+ * @param processName - Name of the process
+ * @returns Array of process versions
+ */
+export async function listProcessVersions(
+  apiKey: string | undefined,
+  marketplace: string,
+  processName: string
+): Promise<ProcessVersion[]> {
+  const response = await apiGet<{
+    data: Array<{
+      'process/createdAt': string;
+      'process/version': number;
+      'process/aliases'?: string[];
+      'process/transactionCount'?: number;
+    }>;
+  }>(
+    apiKey,
+    '/processes/query-versions',
+    { marketplace, name: processName }
+  );
+
+  return response.data.map(v => ({
+    createdAt: v['process/createdAt'],
+    version: v['process/version'],
+    aliases: v['process/aliases'],
+    transactionCount: v['process/transactionCount'],
+  }));
+}
+
+/**
+ * Gets details of a specific process version
+ *
+ * @param apiKey - Sharetribe API key
+ * @param marketplace - Marketplace ID
+ * @param processName - Name of the process
+ * @param options - Optional version or alias to retrieve
+ * @returns Process details including definition and templates
+ */
+export async function getProcess(
+  apiKey: string | undefined,
+  marketplace: string,
+  processName: string,
+  options?: { version?: string; alias?: string }
+): Promise<ProcessDetails> {
+  const queryParams: Record<string, string> = {
+    marketplace,
+    name: processName,
+  };
+
+  if (options?.version) {
+    queryParams.version = options.version;
+  } else if (options?.alias) {
+    queryParams.alias = options.alias;
+  }
+
+  const response = await apiGet<{ data: any }>(apiKey, '/processes/show', queryParams);
+
+  const emailTemplates = (response.data['process/emailTemplates'] || []).map((t: any) => ({
+    name: t['emailTemplate/name'],
+    html: t['emailTemplate/html'],
+    subject: t['emailTemplate/subject'],
+  }));
+
+  return {
+    definition: response.data['process/process'] || response.data.definition,
+    version: response.data['process/version'] || response.data.version,
+    name: response.data['process/name'] || processName,
+    emailTemplates,
+  };
+}
+
+/**
+ * Creates a new transaction process
+ *
+ * @param apiKey - Sharetribe API key
+ * @param marketplace - Marketplace ID
+ * @param processName - Name for the new process
+ * @param definition - Process definition (EDN format)
+ * @returns Created process details
+ */
+export async function createProcess(
+  apiKey: string | undefined,
+  marketplace: string,
+  processName: string,
+  definition: string
+): Promise<CreateProcessResult> {
+  const response = await apiPost<{ data: { 'process/name': string; 'process/version': number } }>(
+    apiKey,
+    '/processes/create',
+    { marketplace },
+    { name: processName, definition }
+  );
+
+  return {
+    name: response.data['process/name'],
+    version: response.data['process/version'],
+  };
+}
+
+/**
+ * Pushes a new version of an existing process
+ *
+ * @param apiKey - Sharetribe API key
+ * @param marketplace - Marketplace ID
+ * @param processName - Name of the process
+ * @param definition - Process definition (EDN format)
+ * @param templates - Optional email templates
+ * @returns Push result with version number
+ */
+export async function pushProcess(
+  apiKey: string | undefined,
+  marketplace: string,
+  processName: string,
+  definition: string,
+  templates?: Array<{ name: string; html: string; subject: string }>
+): Promise<PushProcessResult> {
+  const fields: MultipartField[] = [
+    { name: 'name', value: processName },
+    { name: 'definition', value: definition },
+  ];
+
+  if (templates) {
+    for (const template of templates) {
+      fields.push({ name: `template-html-${template.name}`, value: template.html });
+      fields.push({ name: `template-subject-${template.name}`, value: template.subject });
+    }
+  }
+
+  const response = await apiPostMultipart<{ data: any; meta?: { result?: string } }>(
+    apiKey,
+    '/processes/create-version',
+    { marketplace },
+    fields
+  );
+
+  if (response.meta?.result === 'no-changes') {
+    return { noChanges: true };
+  }
+
+  return {
+    version: response.data['process/version'] || response.data.version,
+  };
+}
+
+/**
+ * Creates a process alias
+ *
+ * @param apiKey - Sharetribe API key
+ * @param marketplace - Marketplace ID
+ * @param processName - Name of the process
+ * @param version - Version number to point the alias to
+ * @param alias - Alias name
+ * @returns Created alias details
+ */
+export async function createAlias(
+  apiKey: string | undefined,
+  marketplace: string,
+  processName: string,
+  version: number,
+  alias: string
+): Promise<AliasResult> {
+  const response = await apiPostTransit<{
+    data: { 'processAlias/alias': string; 'processAlias/version': number };
+  }>(
+    apiKey,
+    '/aliases/create-alias',
+    { marketplace },
+    keywordMap({
+      name: keyword(processName),
+      version,
+      alias: keyword(alias),
+    })
+  );
+
+  return {
+    alias: response.data['processAlias/alias'],
+    version: response.data['processAlias/version'],
+  };
+}
+
+/**
+ * Updates a process alias to point to a different version
+ *
+ * @param apiKey - Sharetribe API key
+ * @param marketplace - Marketplace ID
+ * @param processName - Name of the process
+ * @param version - Version number to point the alias to
+ * @param alias - Alias name
+ * @returns Updated alias details
+ */
+export async function updateAlias(
+  apiKey: string | undefined,
+  marketplace: string,
+  processName: string,
+  version: number,
+  alias: string
+): Promise<AliasResult> {
+  const response = await apiPostTransit<{
+    data: { 'processAlias/alias': string; 'processAlias/version': number };
+  }>(
+    apiKey,
+    '/aliases/update-alias',
+    { marketplace },
+    keywordMap({
+      name: keyword(processName),
+      version,
+      alias: keyword(alias),
+    })
+  );
+
+  return {
+    alias: response.data['processAlias/alias'],
+    version: response.data['processAlias/version'],
+  };
+}
+
+/**
+ * Deletes a process alias
+ *
+ * @param apiKey - Sharetribe API key
+ * @param marketplace - Marketplace ID
+ * @param processName - Name of the process
+ * @param alias - Alias name to delete
+ * @returns Deleted alias name
+ */
+export async function deleteAlias(
+  apiKey: string | undefined,
+  marketplace: string,
+  processName: string,
+  alias: string
+): Promise<{ alias: string }> {
+  const response = await apiPostTransit<{ data: { 'processAlias/alias': string } }>(
+    apiKey,
+    '/aliases/delete-alias',
+    { marketplace },
+    keywordMap({
+      name: keyword(processName),
+      alias: keyword(alias),
+    })
+  );
+
+  return {
+    alias: response.data['processAlias/alias'],
+  };
+}

package/src/sdk-exports.md

@@ -0,0 +1,25 @@
+# SDK Exports Documentation
+
+This SDK provides programmatic access to all Sharetribe CLI commands.
+
+## Modules
+
+- **processes.ts**: Process management (list, create, push, pull, aliases)
+- **search.ts**: Search schema management (list, set, unset) - TODO
+- **assets.ts**: Asset management (pull, push) - TODO
+- **notifications.ts**: Email notifications (preview, send) - TODO
+- **listing-approval.ts**: Listing approval settings - TODO
+- **stripe.ts**: Stripe configuration - TODO
+- **events.ts**: Event webhooks - TODO
+
+## Implementation Status
+
+✅ Processes - Complete
+⏳ Search - In progress
+⏳ Assets - In progress
+⏳ Notifications - In progress
+⏳ Listing approval - In progress
+⏳ Stripe - In progress
+⏳ Events - In progress
+
+Note: For the first release (1.15.0), we're focusing on process management which is the core functionality. Additional commands will be added in future versions while maintaining backward compatibility.

package/src/search.ts

@@ -0,0 +1,273 @@
+/**
+ * Search schema management functions
+ *
+ * Programmatic API for managing search schemas
+ */
+
+import { apiGet, apiPostTransit } from './api/client.js';
+import { keyword, keywordMap } from './api/transit.js';
+
+export interface SearchSchema {
+  schemaFor: string;
+  scope: string;
+  key: string;
+  type: string;
+  defaultValue?: string | number | boolean | string[];
+  doc?: string;
+}
+
+export interface SetSearchSchemaOptions {
+  key: string;
+  scope: string;
+  type: string;
+  doc?: string;
+  defaultValue?: string;
+  schemaFor?: string;
+}
+
+export interface UnsetSearchSchemaOptions {
+  key: string;
+  scope: string;
+  schemaFor?: string;
+}
+
+/**
+ * Valid values for schema-for parameter
+ */
+const VALID_SCHEMA_FOR = ['listing', 'userProfile', 'transaction'];
+
+/**
+ * Valid scopes by schema type
+ */
+const VALID_SCOPES: Record<string, string[]> = {
+  listing: ['metadata', 'public'],
+  userProfile: ['metadata', 'private', 'protected', 'public'],
+  transaction: ['metadata', 'protected'],
+};
+
+/**
+ * Valid types
+ */
+const VALID_TYPES = ['enum', 'multi-enum', 'boolean', 'long', 'text'];
+
+/**
+ * Validates and coerces a default value based on type
+ */
+function coerceDefaultValue(value: string, type: string): string | number | boolean | string[] {
+  if (type === 'boolean') {
+    if (value !== 'true' && value !== 'false') {
+      throw new Error(`Default value must be "true" or "false" for boolean type`);
+    }
+    return value === 'true';
+  }
+
+  if (type === 'long') {
+    const num = parseFloat(value);
+    if (isNaN(num) || !Number.isInteger(num)) {
+      throw new Error(`Default value must be an integer for long type`);
+    }
+    return num;
+  }
+
+  if (type === 'multi-enum') {
+    return value.split(',').map(v => v.trim());
+  }
+
+  return value;
+}
+
+/**
+ * Validates search schema parameters for set operation
+ */
+function validateSetParams(opts: SetSearchSchemaOptions): void {
+  const errors: string[] = [];
+  const schemaFor = opts.schemaFor || 'listing';
+
+  if (opts.key.includes('.')) {
+    errors.push('Key cannot include dots (.) - only top-level keys are allowed');
+  }
+
+  if (!VALID_SCHEMA_FOR.includes(schemaFor)) {
+    errors.push(`schema-for must be one of: ${VALID_SCHEMA_FOR.join(', ')}`);
+  }
+
+  const validScopes = VALID_SCOPES[schemaFor] || [];
+  if (!validScopes.includes(opts.scope)) {
+    errors.push(`scope must be one of: ${validScopes.join(', ')} for ${schemaFor}`);
+  }
+
+  if (!VALID_TYPES.includes(opts.type)) {
+    errors.push(`type must be one of: ${VALID_TYPES.join(', ')}`);
+  }
+
+  if (opts.type === 'text' && schemaFor === 'userProfile') {
+    errors.push('text type is not supported for userProfile schema');
+  }
+
+  if (errors.length > 0) {
+    throw new Error(errors.join('\n'));
+  }
+}
+
+/**
+ * Validates search schema parameters for unset operation
+ */
+function validateUnsetParams(opts: UnsetSearchSchemaOptions): void {
+  const errors: string[] = [];
+  const schemaFor = opts.schemaFor || 'listing';
+
+  if (opts.key.includes('.')) {
+    errors.push('Key cannot include dots (.) - only top-level keys are allowed');
+  }
+
+  if (!VALID_SCHEMA_FOR.includes(schemaFor)) {
+    errors.push(`schema-for must be one of: ${VALID_SCHEMA_FOR.join(', ')}`);
+  }
+
+  const validScopes = VALID_SCOPES[schemaFor] || [];
+  if (!validScopes.includes(opts.scope)) {
+    errors.push(`scope must be one of: ${validScopes.join(', ')} for ${schemaFor}`);
+  }
+
+  if (errors.length > 0) {
+    throw new Error(errors.join('\n'));
+  }
+}
+
+/**
+ * Extracts the name from a namespaced key (e.g., "dataSchema.scope/public" -> "public")
+ */
+function extractName(key: string): string {
+  return key.split('/').pop() || key;
+}
+
+/**
+ * Converts type and cardinality to type label (e.g., "multi-enum" for enum with many cardinality)
+ */
+function getTypeLabel(valueType: string, cardinality?: string): string {
+  const typeName = valueType.split('/').pop() || valueType;
+  if (typeName === 'enum' && cardinality === 'dataSchema.cardinality/many') {
+    return 'multi-enum';
+  }
+  return typeName;
+}
+
+/**
+ * Converts default value to display format
+ */
+function formatDefaultValue(value: unknown): string | number | boolean | string[] | undefined {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+  if (Array.isArray(value)) {
+    return value;
+  }
+  return value as string | number | boolean;
+}
+
+/**
+ * Lists all search schemas for a marketplace
+ *
+ * @param apiKey - Sharetribe API key (optional, reads from auth file if not provided)
+ * @param marketplace - Marketplace ID
+ * @returns Array of search schemas
+ */
+export async function listSearchSchemas(
+  apiKey: string | undefined,
+  marketplace: string
+): Promise<SearchSchema[]> {
+  const response = await apiGet<{
+    data: Array<{
+      'dataSchema/key': string;
+      'dataSchema/scope': string;
+      'dataSchema/valueType': string;
+      'dataSchema/cardinality'?: string;
+      'dataSchema/defaultValue'?: unknown;
+      'dataSchema/doc'?: string;
+      'dataSchema/of': string;
+    }>;
+  }>(
+    apiKey,
+    '/search-schemas/query',
+    {
+      marketplace,
+      of: 'dataSchema.of/userProfile,dataSchema.of/listing,dataSchema.of/transaction',
+    }
+  );
+
+  return response.data.map(s => ({
+    schemaFor: extractName(s['dataSchema/of']),
+    scope: extractName(s['dataSchema/scope']),
+    key: extractName(s['dataSchema/key']),
+    type: getTypeLabel(s['dataSchema/valueType'], s['dataSchema/cardinality']),
+    defaultValue: formatDefaultValue(s['dataSchema/defaultValue']),
+    doc: s['dataSchema/doc'],
+  }));
+}
+
+/**
+ * Sets a search schema field
+ *
+ * @param apiKey - Sharetribe API key (optional, reads from auth file if not provided)
+ * @param marketplace - Marketplace ID
+ * @param options - Schema configuration
+ * @returns Success confirmation
+ */
+export async function setSearchSchema(
+  apiKey: string | undefined,
+  marketplace: string,
+  options: SetSearchSchemaOptions
+): Promise<{ success: true }> {
+  validateSetParams(options);
+
+  const schemaFor = options.schemaFor || 'listing';
+  const isMultiEnum = options.type === 'multi-enum';
+
+  const bodyObj: Record<string, unknown> = {
+    key: keyword(options.key),
+    scope: keyword(`dataSchema.scope/${options.scope}`),
+    valueType: keyword(`dataSchema.type/${isMultiEnum ? 'enum' : options.type}`),
+    cardinality: keyword(isMultiEnum ? 'dataSchema.cardinality/many' : 'dataSchema.cardinality/one'),
+    of: keyword(`dataSchema.of/${schemaFor}`),
+  };
+
+  if (options.doc) {
+    bodyObj.doc = options.doc;
+  }
+
+  if (options.defaultValue !== undefined) {
+    bodyObj.defaultValue = coerceDefaultValue(options.defaultValue, options.type);
+  }
+
+  await apiPostTransit(apiKey, '/search-schemas/set', { marketplace }, keywordMap(bodyObj));
+
+  return { success: true };
+}
+
+/**
+ * Unsets a search schema field
+ *
+ * @param apiKey - Sharetribe API key (optional, reads from auth file if not provided)
+ * @param marketplace - Marketplace ID
+ * @param options - Schema identification
+ * @returns Success confirmation
+ */
+export async function unsetSearchSchema(
+  apiKey: string | undefined,
+  marketplace: string,
+  options: UnsetSearchSchemaOptions
+): Promise<{ success: true }> {
+  validateUnsetParams(options);
+
+  const schemaFor = options.schemaFor || 'listing';
+
+  const bodyObj = {
+    key: keyword(options.key),
+    scope: keyword(`dataSchema.scope/${options.scope}`),
+    of: keyword(`dataSchema.of/${schemaFor}`),
+  };
+
+  await apiPostTransit(apiKey, '/search-schemas/unset', { marketplace }, keywordMap(bodyObj));
+
+  return { success: true };
+}

package/src/stripe.ts

@@ -0,0 +1,39 @@
+/**
+ * Stripe integration management functions
+ *
+ * Programmatic API for managing Stripe integration
+ */
+
+import { apiPost } from './api/client.js';
+
+/**
+ * Supported Stripe API versions
+ */
+export const SUPPORTED_STRIPE_VERSIONS = ['2019-12-03', '2019-09-09', '2019-02-19'] as const;
+
+export type StripeApiVersion = typeof SUPPORTED_STRIPE_VERSIONS[number];
+
+/**
+ * Updates Stripe API version
+ *
+ * @param apiKey - Sharetribe API key (optional, reads from auth file if not provided)
+ * @param marketplace - Marketplace ID
+ * @param version - Stripe API version
+ * @returns Success confirmation
+ */
+export async function updateStripeVersion(
+  apiKey: string | undefined,
+  marketplace: string,
+  version: string
+): Promise<{ success: true }> {
+  // Validate version
+  if (!SUPPORTED_STRIPE_VERSIONS.includes(version as StripeApiVersion)) {
+    throw new Error(
+      `--version should be one of: ${SUPPORTED_STRIPE_VERSIONS.join(', ')}. Was ${version}.`
+    );
+  }
+
+  await apiPost(apiKey, '/stripe/update-version', { marketplace }, { version });
+
+  return { success: true };
+}

package/src/types/jsedn.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Type definitions for jsedn
+ */
+
+declare module 'jsedn' {
+  export function parse(str: string): any;
+  export function kw(name: string): any;
+  export function encode(value: any): string;
+}

package/src/types/transit-js.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Type definitions for transit-js
+ */
+
+declare module 'transit-js' {
+  export function writer(type: string, options?: { handlers?: any }): any;
+  export function reader(type: string): any;
+  export function keyword(name: string): any;
+  export function map(entries: any[]): any;
+}