@supatype/plugin-sdk 0.1.0-alpha.9

package/src/define.ts

@@ -0,0 +1,202 @@
+/**
+ * Builder functions for defining Supatype plugins.
+ *
+ * These are the primary API surface for plugin authors:
+ *   defineFieldType()  — custom field types (e.g., phone, currency)
+ *   defineComposite()  — field bundles (e.g., SEO, address)
+ *   defineProvider()   — service providers (e.g., Stripe, PostHog)
+ *   defineWidget()     — admin panel widgets (e.g., color picker)
+ */
+
+import {
+  PLUGIN_API_VERSION,
+  type FieldTypeDefinition,
+  type CompositeDefinition,
+  type ProviderDefinition,
+  type WidgetDefinition,
+  type PluginMeta,
+} from "./types.js"
+
+// ─── defineFieldType ─────────────────────────────────────────────────────────
+
+/**
+ * Define a custom field type plugin.
+ *
+ * @example
+ * ```ts
+ * import { defineFieldType } from '@supatype/plugin-sdk'
+ *
+ * export default defineFieldType({
+ *   name: 'phone',
+ *   pgType: 'TEXT',
+ *   tsType: 'string',
+ *   validate(value) {
+ *     if (typeof value !== 'string') return 'Must be a string'
+ *     if (!/^\+\d{7,15}$/.test(value)) return 'Invalid phone number (E.164 format required)'
+ *     return null
+ *   },
+ *   widgetPath: './src/PhoneWidget.tsx',
+ *   filterOperators: ['eq', 'neq', 'in', 'like'],
+ * })
+ * ```
+ */
+export function defineFieldType<TValue = unknown>(
+  definition: FieldTypeDefinition<TValue>,
+): FieldTypeDefinition<TValue> & { __supatype: "field" } {
+  return {
+    ...definition,
+    meta: {
+      name: definition.name,
+      description: `Custom field type: ${definition.name}`,
+      types: ["field"],
+      pluginApi: PLUGIN_API_VERSION,
+      ...definition.meta,
+    },
+    __supatype: "field" as const,
+  }
+}
+
+// ─── defineComposite ─────────────────────────────────────────────────────────
+
+/**
+ * Define a composite plugin (field bundle).
+ *
+ * @example
+ * ```ts
+ * import { defineComposite } from '@supatype/plugin-sdk'
+ *
+ * export default defineComposite({
+ *   name: 'seo',
+ *   label: 'SEO Meta',
+ *   fields: [
+ *     { name: 'meta_title', type: 'text', options: { maxLength: 60 } },
+ *     { name: 'meta_description', type: 'text', options: { maxLength: 160 } },
+ *     { name: 'og_image', type: 'text' },
+ *     { name: 'canonical_url', type: 'text' },
+ *     { name: 'no_index', type: 'boolean', defaultValue: false },
+ *   ],
+ *   adminGroup: { collapsible: true, defaultCollapsed: true },
+ * })
+ * ```
+ */
+export function defineComposite(
+  definition: CompositeDefinition,
+): CompositeDefinition & { __supatype: "composite" } {
+  return {
+    ...definition,
+    meta: {
+      name: definition.name,
+      description: `Composite: ${definition.label}`,
+      types: ["composite"],
+      pluginApi: PLUGIN_API_VERSION,
+      ...definition.meta,
+    },
+    __supatype: "composite" as const,
+  }
+}
+
+// ─── defineProvider ──────────────────────────────────────────────────────────
+
+/**
+ * Define a service provider plugin.
+ *
+ * @example
+ * ```ts
+ * import { defineProvider, type CommerceProvider } from '@supatype/plugin-sdk'
+ *
+ * export default defineProvider<StripeConfig>({
+ *   name: 'stripe',
+ *   category: 'commerce',
+ *   label: 'Stripe',
+ *   configSchema: {
+ *     secretKey: { type: 'string', label: 'Secret Key', required: true, secret: true },
+ *     webhookSecret: { type: 'string', label: 'Webhook Secret', required: true, secret: true },
+ *   },
+ *   create(config): CommerceProvider {
+ *     return new StripeCommerceProvider(config)
+ *   },
+ * })
+ * ```
+ */
+export function defineProvider<TConfig = Record<string, unknown>>(
+  definition: ProviderDefinition<TConfig>,
+): ProviderDefinition<TConfig> & { __supatype: "provider" } {
+  return {
+    ...definition,
+    meta: {
+      name: definition.name,
+      description: `${definition.category} provider: ${definition.label}`,
+      types: ["provider"],
+      pluginApi: PLUGIN_API_VERSION,
+      ...definition.meta,
+    },
+    __supatype: "provider" as const,
+  }
+}
+
+// ─── defineWidget ────────────────────────────────────────────────────────────
+
+/**
+ * Define a standalone widget plugin.
+ *
+ * @example
+ * ```ts
+ * import { defineWidget } from '@supatype/plugin-sdk'
+ *
+ * export default defineWidget({
+ *   name: 'color-picker',
+ *   label: 'Colour Picker',
+ *   compatibleTypes: ['text', 'varchar'],
+ *   componentPath: './src/ColorPickerWidget.tsx',
+ * })
+ * ```
+ */
+export function defineWidget(
+  definition: WidgetDefinition,
+): WidgetDefinition & { __supatype: "widget" } {
+  return {
+    ...definition,
+    meta: {
+      name: definition.name,
+      description: `Widget: ${definition.label}`,
+      types: ["widget"],
+      pluginApi: PLUGIN_API_VERSION,
+      ...definition.meta,
+    },
+    __supatype: "widget" as const,
+  }
+}
+
+// ─── Plugin definition union ─────────────────────────────────────────────────
+
+export type AnyPluginDefinition =
+  | (FieldTypeDefinition & { __supatype: "field" })
+  | (CompositeDefinition & { __supatype: "composite" })
+  | (ProviderDefinition & { __supatype: "provider" })
+  | (WidgetDefinition & { __supatype: "widget" })
+
+/**
+ * Check if a value is a Supatype plugin definition.
+ */
+export function isPluginDefinition(value: unknown): value is AnyPluginDefinition {
+  return typeof value === "object" && value !== null && "__supatype" in value
+}
+
+/**
+ * Validate plugin API version compatibility.
+ */
+export function checkPluginApiVersion(meta: PluginMeta | undefined): {
+  compatible: boolean
+  message?: string | undefined
+} {
+  if (!meta) return { compatible: true }
+
+  if (meta.pluginApi !== PLUGIN_API_VERSION) {
+    return {
+      compatible: false,
+      message: `Plugin "${meta.name}" targets plugin API v${meta.pluginApi}, but the current version is v${PLUGIN_API_VERSION}. The plugin may not work correctly.`,
+    }
+  }
+
+  return { compatible: true }
+}

package/src/docgen.ts

@@ -0,0 +1,172 @@
+/**
+ * Plugin documentation generator.
+ *
+ * Generates Markdown documentation from a plugin's type definitions.
+ */
+
+import type {
+  FieldTypeDefinition,
+  CompositeDefinition,
+  ProviderDefinition,
+  WidgetDefinition,
+} from "./types.js"
+import type { AnyPluginDefinition } from "./define.js"
+
+function escapeMarkdown(text: string): string {
+  return text.replace(/[|\\`*_{}[\]()#+\-.!]/g, "\\$&")
+}
+
+function generateFieldDocs(def: FieldTypeDefinition & { __supatype: "field" }): string {
+  const lines: string[] = []
+
+  lines.push("## Field Type")
+  lines.push("")
+  lines.push(`| Property | Value |`)
+  lines.push(`| --- | --- |`)
+  lines.push(`| Name | \`${def.name}\` |`)
+  lines.push(`| Postgres Type | \`${def.pgType}\` |`)
+  lines.push(`| TypeScript Type | \`${def.tsType}\` |`)
+
+  if (def.validate !== undefined) {
+    lines.push(`| Validate | \`${def.validate.toString().slice(0, 80)}\` |`)
+  }
+
+  if (def.filterOperators !== undefined) {
+    lines.push(`| Filter Operators | ${def.filterOperators.map(o => `\`${o}\``).join(", ")} |`)
+  }
+
+  if (def.widgetPath !== undefined) {
+    lines.push(`| Widget Path | \`${def.widgetPath}\` |`)
+  }
+
+  lines.push("")
+
+  if (def.constraints !== undefined && def.constraints.length > 0) {
+    lines.push("### Constraints")
+    lines.push("")
+    for (const c of def.constraints) {
+      lines.push(`- \`${c}\``)
+    }
+    lines.push("")
+  }
+
+  return lines.join("\n")
+}
+
+function generateCompositeDocs(def: CompositeDefinition & { __supatype: "composite" }): string {
+  const lines: string[] = []
+
+  lines.push("## Composite")
+  lines.push("")
+  lines.push(`**Label:** ${escapeMarkdown(def.label)}`)
+  lines.push("")
+  lines.push("### Fields")
+  lines.push("")
+  lines.push(`| Name | Type | Required | Default |`)
+  lines.push(`| --- | --- | --- | --- |`)
+
+  for (const field of def.fields) {
+    const req = field.required === true ? "Yes" : "No"
+    const defaultVal = field.defaultValue !== undefined ? `\`${String(field.defaultValue)}\`` : "-"
+    lines.push(`| ${field.name} | \`${field.type}\` | ${req} | ${defaultVal} |`)
+  }
+
+  lines.push("")
+
+  if (def.adminGroup !== undefined) {
+    lines.push("### Admin Group")
+    lines.push("")
+    if (def.adminGroup.collapsible !== undefined) {
+      lines.push(`- Collapsible: ${def.adminGroup.collapsible}`)
+    }
+    if (def.adminGroup.defaultCollapsed !== undefined) {
+      lines.push(`- Default Collapsed: ${def.adminGroup.defaultCollapsed}`)
+    }
+    lines.push("")
+  }
+
+  return lines.join("\n")
+}
+
+function generateProviderDocs(def: ProviderDefinition & { __supatype: "provider" }): string {
+  const lines: string[] = []
+
+  lines.push("## Provider")
+  lines.push("")
+  lines.push(`**Category:** ${def.category}`)
+  lines.push("")
+
+  if (def.configSchema && Object.keys(def.configSchema).length > 0) {
+    lines.push("### Config Schema")
+    lines.push("")
+    lines.push(`| Field | Type | Label | Required | Secret |`)
+    lines.push(`| --- | --- | --- | --- | --- |`)
+
+    for (const [key, schema] of Object.entries(def.configSchema)) {
+      const req = schema.required === true ? "Yes" : "No"
+      const secret = schema.secret === true ? "Yes" : "No"
+      lines.push(`| ${key} | \`${schema.type}\` | ${escapeMarkdown(schema.label)} | ${req} | ${secret} |`)
+    }
+
+    lines.push("")
+  }
+
+  return lines.join("\n")
+}
+
+function generateWidgetDocs(def: WidgetDefinition & { __supatype: "widget" }): string {
+  const lines: string[] = []
+
+  lines.push("## Widget")
+  lines.push("")
+  lines.push(`| Property | Value |`)
+  lines.push(`| --- | --- |`)
+  lines.push(`| Name | \`${def.name}\` |`)
+  lines.push(`| Label | ${escapeMarkdown(def.label)} |`)
+  lines.push(`| Compatible Types | ${def.compatibleTypes.map(t => `\`${t}\``).join(", ")} |`)
+  lines.push(`| Component Path | \`${def.componentPath}\` |`)
+  lines.push("")
+
+  return lines.join("\n")
+}
+
+/**
+ * Generate Markdown documentation from a plugin definition.
+ *
+ * The output includes YAML frontmatter with the plugin name, type, and version,
+ * followed by type-specific documentation sections.
+ */
+export function generatePluginDocs(definition: AnyPluginDefinition): string {
+  const name = (definition as { name: string }).name
+  const type = definition.__supatype
+  const version = definition.meta?.pluginApi ?? 1
+
+  const frontmatter = [
+    "---",
+    `name: "${name}"`,
+    `type: "${type}"`,
+    `version: ${version}`,
+    "---",
+  ].join("\n")
+
+  const header = `# ${name}\n`
+
+  let body: string
+
+  switch (definition.__supatype) {
+    case "field":
+      body = generateFieldDocs(definition)
+      break
+    case "composite":
+      body = generateCompositeDocs(definition)
+      break
+    case "provider":
+      body = generateProviderDocs(definition)
+      break
+    case "widget":
+      body = generateWidgetDocs(definition)
+      break
+  }
+
+  return `${frontmatter}\n\n${header}\n${body}`
+}

package/src/index.ts

@@ -0,0 +1,58 @@
+// @supatype/plugin-sdk — Plugin development kit for Supatype extensions
+
+// Core types
+export {
+  PLUGIN_API_VERSION,
+  type PluginType,
+  type PluginMeta,
+  type FieldTypeDefinition,
+  type CompositeDefinition,
+  type CompositeFieldDef,
+  type ProviderDefinition,
+  type ProviderCategory,
+  type WidgetDefinition,
+  type WidgetProps,
+  type CommerceProvider,
+  type TrackingProvider,
+  type EmailProvider,
+  type StorageProvider,
+  type AuthProvider,
+  type SSLProvider,
+} from "./types.js"
+
+// Builder functions
+export {
+  defineFieldType,
+  defineComposite,
+  defineProvider,
+  defineWidget,
+  isPluginDefinition,
+  checkPluginApiVersion,
+  type AnyPluginDefinition,
+} from "./define.js"
+
+// Documentation generator
+export { generatePluginDocs } from "./docgen.js"
+
+// Plugin loading and registry
+export {
+  registerPlugin,
+  getRegisteredPlugins,
+  getPluginsByType,
+  getFieldTypePlugin,
+  getProviderPlugin,
+  clearPluginRegistry,
+  isSupatypePlugin,
+  sortByLoadOrder,
+  detectConflicts,
+  validateProviders,
+  getPluginFieldTypeMap,
+  getPluginFieldPgTypeMap,
+  expandPluginComposites,
+  type RegisteredPlugin,
+  type PluginPackageInfo,
+  type PluginConflict,
+  type ProviderValidationResult,
+  type FieldPgTypeInfo,
+  type CompositeExpansion,
+} from "./loader.js"