@contractspec/example.integration-stripe 3.7.6 → 3.7.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractspec/example.integration-stripe",
-  "version": "3.7.6",
+  "version": "3.7.10",
   "description": "Integration example – Stripe Payments (blueprint + workflow + tenant config).",
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -47,6 +47,13 @@
       "node": "./dist/node/example.js",
       "default": "./dist/example.js"
     },
+    "./integration": {
+      "types": "./dist/integration.d.ts",
+      "browser": "./dist/browser/integration.js",
+      "bun": "./dist/integration.js",
+      "node": "./dist/node/integration.js",
+      "default": "./dist/integration.js"
+    },
     "./integration-stripe.feature": {
       "types": "./dist/integration-stripe.feature.d.ts",
       "browser": "./dist/browser/integration-stripe.feature.js",
@@ -78,21 +85,21 @@
     "dev": "contractspec-bun-build dev",
     "clean": "rimraf dist .turbo",
     "lint": "bun lint:fix",
-    "lint:fix": "eslint src --fix",
-    "lint:check": "eslint src",
+    "lint:fix": "biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .",
+    "lint:check": "biome check .",
     "test": "bun test --pass-with-no-tests",
     "prebuild": "contractspec-bun-build prebuild",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@contractspec/lib.schema": "3.7.6",
-    "@contractspec/lib.contracts-spec": "3.7.6",
-    "@contractspec/lib.contracts-integrations": "3.7.6"
+    "@contractspec/lib.schema": "3.7.8",
+    "@contractspec/lib.contracts-spec": "4.1.2",
+    "@contractspec/lib.contracts-integrations": "3.8.2"
   },
   "devDependencies": {
-    "@contractspec/tool.typescript": "3.7.6",
+    "@contractspec/tool.typescript": "3.7.8",
     "typescript": "^5.9.3",
-    "@contractspec/tool.bun": "3.7.6"
+    "@contractspec/tool.bun": "3.7.8"
   },
   "publishConfig": {
     "access": "public",
@@ -139,6 +146,13 @@
         "node": "./dist/node/example.js",
         "default": "./dist/example.js"
       },
+      "./integration": {
+        "types": "./dist/integration.d.ts",
+        "browser": "./dist/browser/integration.js",
+        "bun": "./dist/integration.js",
+        "node": "./dist/node/integration.js",
+        "default": "./dist/integration.js"
+      },
       "./integration-stripe.feature": {
         "types": "./dist/integration-stripe.feature.d.ts",
         "browser": "./dist/browser/integration-stripe.feature.js",

package/src/blueprint.ts

@@ -1,62 +1,62 @@
-import type { AppBlueprintSpec } from '@contractspec/lib.contracts-spec/app-config/spec';
+import { defineAppConfig } from '@contractspec/lib.contracts-spec/app-config/spec';
 import {
-  OwnersEnum,
-  StabilityEnum,
-  TagsEnum,
+	OwnersEnum,
+	StabilityEnum,
+	TagsEnum,
 } from '@contractspec/lib.contracts-spec/ownership';
+import { collectPaymentWorkflow } from './workflow';
 
-export const artisanStripeBlueprint: AppBlueprintSpec = {
-  meta: {
-    key: 'artisan.payments.stripe',
-    version: '1.0.0',
-    appId: 'artisan',
-    title: 'ArtisanOS Stripe Payments',
-    description:
-      'Blueprint enabling card payments for ArtisanOS merchants via the Stripe integration.',
-    domain: 'payments',
-    owners: [OwnersEnum.PlatformCore],
-    tags: [TagsEnum.Marketplace, 'stripe', 'payments'],
-    stability: StabilityEnum.Experimental,
-  },
-  capabilities: {
-    enabled: [{ key: 'payments.psp', version: '1.0.0' }],
-  },
-  integrationSlots: [
-    {
-      slotId: 'primary-payments',
-      requiredCategory: 'payments',
-      allowedModes: ['managed', 'byok'],
-      requiredCapabilities: [{ key: 'payments.psp', version: '1.0.0' }],
-      required: true,
-      description:
-        'Primary card processor slot. Bind the tenant Stripe connection here.',
-    },
-  ],
-  branding: {
-    appNameKey: 'artisan.payments.appName',
-    assets: [
-      { type: 'logo', url: 'https://cdn.artisanos.dev/branding/logo.png' },
-      {
-        type: 'favicon',
-        url: 'https://cdn.artisanos.dev/branding/favicon.ico',
-      },
-    ],
-    colorTokens: {
-      primary: 'colors.brand.primary',
-      secondary: 'colors.brand.secondary',
-    },
-  },
-  translationCatalog: {
-    key: 'artisan.payments.catalog',
-    version: '1.0.0',
-  },
-  workflows: {
-    collectPayment: {
-      key: 'artisan.payments.collectPayment',
-      version: '1.0.0',
-    },
-  },
-  policies: [{ key: 'artisan.payments.default', version: '1.0.0' }],
-  notes:
-    'Install this blueprint and pair it with the Stripe integration connection to enable card collection.',
-};
+export const artisanStripeBlueprint = defineAppConfig({
+	meta: {
+		key: 'artisan.payments.stripe',
+		version: '1.0.0',
+		appId: 'artisan',
+		title: 'ArtisanOS Stripe Payments',
+		description:
+			'Blueprint enabling card payments for ArtisanOS merchants via the Stripe integration.',
+		domain: 'payments',
+		owners: [OwnersEnum.PlatformCore],
+		tags: [TagsEnum.Marketplace, 'stripe', 'payments'],
+		stability: StabilityEnum.Experimental,
+	},
+	capabilities: {
+		enabled: [{ key: 'payments.psp', version: '1.0.0' }],
+	},
+	integrationSlots: [
+		{
+			slotId: 'primary-payments',
+			requiredCategory: 'payments',
+			allowedModes: ['managed', 'byok'],
+			requiredCapabilities: [{ key: 'payments.psp', version: '1.0.0' }],
+			required: true,
+			description:
+				'Primary card processor slot. Bind the tenant Stripe connection here.',
+		},
+	],
+	branding: {
+		appNameKey: 'artisan.payments.appName',
+		assets: [
+			{ type: 'logo', url: 'https://cdn.artisanos.dev/branding/logo.png' },
+			{
+				type: 'favicon',
+				url: 'https://cdn.artisanos.dev/branding/favicon.ico',
+			},
+		],
+		colorTokens: {
+			primary: 'colors.brand.primary',
+			secondary: 'colors.brand.secondary',
+		},
+	},
+	translationCatalog: {
+		key: 'artisan.payments.catalog',
+		version: '1.0.0',
+	},
+	workflows: {
+		collectPayment: {
+			key: collectPaymentWorkflow.meta.key,
+			version: collectPaymentWorkflow.meta.version,
+		},
+	},
+	notes:
+		'Install this blueprint and pair it with the Stripe integration connection to enable card collection.',
+});

package/src/connection.sample.ts

@@ -1,21 +1,22 @@
 import type { IntegrationConnection } from '@contractspec/lib.contracts-integrations';
+import { StripePaymentsIntegrationSpec } from './integration';
 
 export const stripeLiveConnection: IntegrationConnection = {
-  meta: {
-    id: 'conn-stripe-live',
-    tenantId: 'artisan-co',
-    integrationKey: 'payments.stripe',
-    integrationVersion: '1',
-    label: 'Stripe Production',
-    environment: 'production',
-    createdAt: '2026-01-01T00:00:00.000Z',
-    updatedAt: '2026-01-01T00:00:00.000Z',
-  },
-  ownershipMode: 'managed',
-  config: {
-    accountId: 'acct_xxx',
-  },
-  secretProvider: 'vault',
-  secretRef: 'vault://integrations/artisan-co/conn-stripe-live',
-  status: 'connected',
+	meta: {
+		id: 'conn-stripe-live',
+		tenantId: 'artisan-co',
+		integrationKey: StripePaymentsIntegrationSpec.meta.key,
+		integrationVersion: StripePaymentsIntegrationSpec.meta.version,
+		label: 'Stripe Production',
+		environment: 'production',
+		createdAt: '2026-01-01T00:00:00.000Z',
+		updatedAt: '2026-01-01T00:00:00.000Z',
+	},
+	ownershipMode: 'managed',
+	config: {
+		accountId: 'acct_xxx',
+	},
+	secretProvider: 'vault',
+	secretRef: 'vault://integrations/artisan-co/conn-stripe-live',
+	status: 'connected',
 };

package/src/contracts.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, test } from 'bun:test';
+import {
+	artisanStripeBlueprint,
+	collectPaymentWorkflow,
+	IntegrationStripeFeature,
+	StripePaymentsIntegrationSpec,
+	stripeLiveConnection,
+} from './index';
+
+describe('@contractspec/example.integration-stripe', () => {
+	test('exports the canonical integration, workflow, and app config', () => {
+		expect(StripePaymentsIntegrationSpec.meta.key).toBe(
+			'integration-stripe.integration.psp'
+		);
+		expect(collectPaymentWorkflow.meta.key).toBe(
+			'integration-stripe.workflow.payment'
+		);
+		expect(artisanStripeBlueprint.workflows).toEqual({
+			collectPayment: {
+				key: collectPaymentWorkflow.meta.key,
+				version: collectPaymentWorkflow.meta.version,
+			},
+		});
+		expect(IntegrationStripeFeature.integrations).toEqual([
+			{
+				key: StripePaymentsIntegrationSpec.meta.key,
+				version: StripePaymentsIntegrationSpec.meta.version,
+			},
+		]);
+		expect(stripeLiveConnection.meta.integrationKey).toBe(
+			StripePaymentsIntegrationSpec.meta.key
+		);
+	});
+});

package/src/docs/integration-stripe.docblock.ts

@@ -2,27 +2,27 @@ import type { DocBlock } from '@contractspec/lib.contracts-spec/docs';
 import { registerDocBlocks } from '@contractspec/lib.contracts-spec/docs';
 
 const blocks: DocBlock[] = [
-  {
-    id: 'docs.examples.integration-stripe',
-    title: 'Integration Example — Stripe Payments',
-    summary:
-      'How to wire IntegrationSpec/TenantAppConfig + blueprint + workflow to enable Stripe-backed payments.',
-    kind: 'reference',
-    visibility: 'public',
-    route: '/docs/examples/integration-stripe',
-    tags: ['stripe', 'payments', 'integrations', 'example'],
-    body: `## Included\n- App blueprint enabling \`payments.psp\` capability.\n- Workflow invoking Stripe operations (prepare → charge → confirm).\n- Tenant app config binding workflow to an IntegrationConnection.\n\n## Notes\n- Secrets live in secret providers; connection config is non-secret.\n- Use \`ctx.resolvedAppConfig\` in operation executors to access integrations, branding, and translations.`,
-  },
-  {
-    id: 'docs.examples.integration-stripe.usage',
-    title: 'Stripe Integration Example — Usage',
-    summary: 'How to use the blueprint, workflow, and tenant config together.',
-    kind: 'usage',
-    visibility: 'public',
-    route: '/docs/examples/integration-stripe/usage',
-    tags: ['stripe', 'usage'],
-    body: `## Usage\n1) Register the blueprint + workflow + catalog in your registry.\n2) Persist an IntegrationConnection (see connection sample).\n3) Bind the tenant app config to the connection.\n\n## Guardrails\n- Never log secrets.\n- Keep payment semantics spec-defined; gate breaking changes behind flags.`,
-  },
+	{
+		id: 'docs.examples.integration-stripe',
+		title: 'Integration Example — Stripe Payments',
+		summary:
+			'How to wire IntegrationSpec/TenantAppConfig + blueprint + workflow to enable Stripe-backed payments.',
+		kind: 'reference',
+		visibility: 'public',
+		route: '/docs/examples/integration-stripe',
+		tags: ['stripe', 'payments', 'integrations', 'example'],
+		body: `## Included\n- App blueprint enabling \`payments.psp\` capability.\n- Workflow invoking Stripe operations (prepare → charge → confirm).\n- Tenant app config binding workflow to an IntegrationConnection.\n\n## Notes\n- Secrets live in secret providers; connection config is non-secret.\n- Use \`ctx.resolvedAppConfig\` in operation executors to access integrations, branding, and translations.`,
+	},
+	{
+		id: 'docs.examples.integration-stripe.usage',
+		title: 'Stripe Integration Example — Usage',
+		summary: 'How to use the blueprint, workflow, and tenant config together.',
+		kind: 'usage',
+		visibility: 'public',
+		route: '/docs/examples/integration-stripe/usage',
+		tags: ['stripe', 'usage'],
+		body: `## Usage\n1) Register the blueprint + workflow + catalog in your registry.\n2) Persist an IntegrationConnection (see connection sample).\n3) Bind the tenant app config to the connection.\n\n## Guardrails\n- Never log secrets.\n- Keep payment semantics spec-defined; gate breaking changes behind flags.`,
+	},
 ];
 
 registerDocBlocks(blocks);

package/src/example.ts

@@ -1,32 +1,32 @@
 import { defineExample } from '@contractspec/lib.contracts-spec';
 
 const example = defineExample({
-  meta: {
-    key: 'integration-stripe',
-    version: '1.0.0',
-    title: 'Integration — Stripe Payments',
-    description:
-      'Wire AppBlueprint + Workflow + TenantAppConfig to enable Stripe-backed payments (spec-first integration pattern).',
-    kind: 'integration',
-    visibility: 'public',
-    stability: 'experimental',
-    owners: ['@platform.core'],
-    tags: ['stripe', 'payments', 'integration', 'blueprint', 'workflow'],
-  },
-  docs: {
-    rootDocId: 'docs.examples.integration-stripe',
-    usageDocId: 'docs.examples.integration-stripe.usage',
-  },
-  entrypoints: {
-    packageName: '@contractspec/example.integration-stripe',
-    docs: './docs',
-  },
-  surfaces: {
-    templates: true,
-    sandbox: { enabled: true, modes: ['markdown', 'specs'] },
-    studio: { enabled: true, installable: true },
-    mcp: { enabled: true },
-  },
+	meta: {
+		key: 'integration-stripe',
+		version: '1.0.0',
+		title: 'Integration — Stripe Payments',
+		description:
+			'Wire AppBlueprint + Workflow + TenantAppConfig to enable Stripe-backed payments (spec-first integration pattern).',
+		kind: 'integration',
+		visibility: 'public',
+		stability: 'experimental',
+		owners: ['@platform.core'],
+		tags: ['stripe', 'payments', 'integration', 'blueprint', 'workflow'],
+	},
+	docs: {
+		rootDocId: 'docs.examples.integration-stripe',
+		usageDocId: 'docs.examples.integration-stripe.usage',
+	},
+	entrypoints: {
+		packageName: '@contractspec/example.integration-stripe',
+		docs: './docs',
+	},
+	surfaces: {
+		templates: true,
+		sandbox: { enabled: true, modes: ['markdown', 'specs'] },
+		studio: { enabled: true, installable: true },
+		mcp: { enabled: true },
+	},
 });
 
 export default example;

package/src/index.ts

@@ -1,7 +1,8 @@
 export * from './blueprint';
-export * from './workflow';
-export * from './tenant';
 export * from './connection.sample';
-export * from './integration-stripe.feature';
 export { default as example } from './example';
+export * from './integration';
+export * from './integration-stripe.feature';
+export * from './tenant';
+export * from './workflow';
 import './docs';

package/src/integration-stripe.feature.ts

@@ -1,28 +1,36 @@
 import { defineFeature } from '@contractspec/lib.contracts-spec';
+import { StripePaymentsIntegrationSpec } from './integration';
+import { collectPaymentWorkflow } from './workflow';
 
 export const IntegrationStripeFeature = defineFeature({
-  meta: {
-    key: 'integration-stripe',
-    version: '1.0.0',
-    title: 'Stripe Payments Integration',
-    description:
-      'Stripe payments integration with blueprint, workflow, and tenant configuration',
-    domain: 'integration',
-    owners: ['@integration-team'],
-    tags: ['integration', 'stripe', 'payments'],
-    stability: 'experimental',
-  },
+	meta: {
+		key: 'integration-stripe',
+		version: '1.0.0',
+		title: 'Stripe Payments Integration',
+		description:
+			'Stripe payments integration with blueprint, workflow, and tenant configuration',
+		domain: 'integration',
+		owners: ['@integration-team'],
+		tags: ['integration', 'stripe', 'payments'],
+		stability: 'experimental',
+	},
 
-  integrations: [
-    { key: 'integration-stripe.integration.psp', version: '1.0.0' },
-  ],
+	integrations: [
+		{
+			key: StripePaymentsIntegrationSpec.meta.key,
+			version: StripePaymentsIntegrationSpec.meta.version,
+		},
+	],
 
-  workflows: [{ key: 'integration-stripe.workflow.payment', version: '1.0.0' }],
+	workflows: [
+		{
+			key: collectPaymentWorkflow.meta.key,
+			version: collectPaymentWorkflow.meta.version,
+		},
+	],
 
-  policies: [{ key: 'integration-stripe.policy.payments', version: '1.0.0' }],
-
-  docs: [
-    'docs.examples.integration-stripe',
-    'docs.examples.integration-stripe.usage',
-  ],
+	docs: [
+		'docs.examples.integration-stripe',
+		'docs.examples.integration-stripe.usage',
+	],
 });

package/src/integration.ts

@@ -0,0 +1,79 @@
+import { defineIntegration } from '@contractspec/lib.contracts-spec/integrations/spec';
+import {
+	OwnersEnum,
+	StabilityEnum,
+	TagsEnum,
+} from '@contractspec/lib.contracts-spec/ownership';
+import { defineSchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';
+
+const StripeConfigModel = defineSchemaModel({
+	name: 'StripePaymentsIntegrationConfig',
+	description: 'Managed configuration required to connect a Stripe account.',
+	fields: {
+		accountId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+		webhookEndpoint: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false,
+		},
+	},
+});
+
+const StripeSecretModel = defineSchemaModel({
+	name: 'StripePaymentsIntegrationSecret',
+	description: 'Secret material stored out-of-band for the Stripe provider.',
+	fields: {
+		apiKey: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+		webhookSecret: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false,
+		},
+	},
+});
+
+export const StripePaymentsIntegrationSpec = defineIntegration({
+	meta: {
+		key: 'integration-stripe.integration.psp',
+		version: '1.0.0',
+		title: 'Stripe Payments Integration',
+		description:
+			'Integration contract for managed or BYOK Stripe card processing.',
+		domain: 'payments',
+		category: 'payments',
+		owners: [OwnersEnum.PlatformCore],
+		tags: [TagsEnum.Marketplace, 'stripe', 'payments'],
+		stability: StabilityEnum.Experimental,
+	},
+	supportedModes: ['managed', 'byok'],
+	capabilities: {
+		provides: [{ key: 'payments.psp', version: '1.0.0' }],
+	},
+	configSchema: {
+		schema: StripeConfigModel,
+		example: {
+			accountId: 'acct_demo_artisan',
+			webhookEndpoint: 'https://pay.artisanos.dev/webhooks/stripe',
+		},
+	},
+	secretSchema: {
+		schema: StripeSecretModel,
+		example: {
+			apiKey: 'sk_live_redacted',
+			webhookSecret: 'whsec_redacted',
+		},
+	},
+	healthCheck: {
+		method: 'ping',
+		timeoutMs: 5000,
+	},
+	docsUrl: 'https://docs.stripe.com',
+	constraints: {
+		rateLimit: {
+			rpm: 1000,
+		},
+	},
+	byokSetup: {
+		setupInstructions:
+			'Create a restricted API key and webhook endpoint, then bind the secret reference to the tenant connection.',
+		requiredScopes: ['charges:write', 'customers:read', 'webhooks:write'],
+	},
+});

package/src/tenant.ts

@@ -1,53 +1,53 @@
 import type { TenantAppConfig } from '@contractspec/lib.contracts-spec/app-config/spec';
 
 export const artisanStripeTenantConfig: TenantAppConfig = {
-  meta: {
-    id: 'tenant-config-artisan-stripe',
-    tenantId: 'artisan-co',
-    appId: 'artisan',
-    blueprintName: 'artisan.payments.stripe',
-    blueprintVersion: '1.0.0',
-    environment: 'production',
-    version: '1.0.0',
-    status: 'published',
-    createdAt: new Date().toISOString(),
-    updatedAt: new Date().toISOString(),
-  },
-  integrations: [
-    {
-      slotId: 'primary-payments',
-      connectionId: 'conn-stripe-live',
-      scope: {
-        workflows: ['collectPayment'],
-        operations: ['payments.stripe.chargeCard'],
-      },
-    },
-  ],
-  knowledge: [],
-  locales: {
-    defaultLocale: 'en',
-    enabledLocales: ['en', 'fr'],
-  },
-  translationOverrides: {
-    entries: [
-      {
-        key: 'artisan.payments.appName',
-        locale: 'en',
-        value: 'Artisan Payments Portal',
-      },
-    ],
-  },
-  branding: {
-    appName: { en: 'Artisan Payments Portal' },
-    assets: [
-      { type: 'logo', url: 'https://tenant.artisanos.dev/logo.png' },
-      { type: 'logo-dark', url: 'https://tenant.artisanos.dev/logo-dark.png' },
-    ],
-    colors: {
-      primary: '#F97316',
-      secondary: '#1F2937',
-    },
-    customDomain: 'pay.artisanos.dev',
-  },
-  notes: 'Stripe connection bound for production payments.',
+	meta: {
+		id: 'tenant-config-artisan-stripe',
+		tenantId: 'artisan-co',
+		appId: 'artisan',
+		blueprintName: 'artisan.payments.stripe',
+		blueprintVersion: '1.0.0',
+		environment: 'production',
+		version: '1.0.0',
+		status: 'published',
+		createdAt: new Date().toISOString(),
+		updatedAt: new Date().toISOString(),
+	},
+	integrations: [
+		{
+			slotId: 'primary-payments',
+			connectionId: 'conn-stripe-live',
+			scope: {
+				workflows: ['collectPayment'],
+				operations: ['payments.stripe.chargeCard'],
+			},
+		},
+	],
+	knowledge: [],
+	locales: {
+		defaultLocale: 'en',
+		enabledLocales: ['en', 'fr'],
+	},
+	translationOverrides: {
+		entries: [
+			{
+				key: 'artisan.payments.appName',
+				locale: 'en',
+				value: 'Artisan Payments Portal',
+			},
+		],
+	},
+	branding: {
+		appName: { en: 'Artisan Payments Portal' },
+		assets: [
+			{ type: 'logo', url: 'https://tenant.artisanos.dev/logo.png' },
+			{ type: 'logo-dark', url: 'https://tenant.artisanos.dev/logo-dark.png' },
+		],
+		colors: {
+			primary: '#F97316',
+			secondary: '#1F2937',
+		},
+		customDomain: 'pay.artisanos.dev',
+	},
+	notes: 'Stripe connection bound for production payments.',
 };