@flowdular/sdk 0.1.0

package/.ai/references/catalog/migrations/0004_catalog_idempotency_ledger.down.sql

@@ -0,0 +1,3 @@
+DROP POLICY IF EXISTS catalog_idempotency_ledger_tenant_policy ON catalog_idempotency_ledger;
+DROP INDEX IF EXISTS catalog_idempotency_ledger_tenant_operation_idx;
+DROP TABLE IF EXISTS catalog_idempotency_ledger;

package/.ai/references/catalog/migrations/0004_catalog_idempotency_ledger.up.sql

@@ -0,0 +1,19 @@
+CREATE TABLE IF NOT EXISTS catalog_idempotency_ledger (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  idempotency_key TEXT NOT NULL CHECK (length(idempotency_key) BETWEEN 8 AND 128),
+  operation_id TEXT NOT NULL CHECK (length(operation_id) BETWEEN 3 AND 160),
+  input_digest TEXT NOT NULL CHECK (length(input_digest) = 71),
+  outcome TEXT NOT NULL CHECK (outcome = 'succeeded'),
+  result_json TEXT NOT NULL CHECK (result_json::jsonb IS NOT NULL),
+  result_digest TEXT NOT NULL CHECK (length(result_digest) = 71),
+  created_at BIGINT NOT NULL,
+  UNIQUE (tenant_id, idempotency_key)
+);
+CREATE INDEX IF NOT EXISTS catalog_idempotency_ledger_tenant_operation_idx
+  ON catalog_idempotency_ledger (tenant_id, operation_id, created_at, id);
+ALTER TABLE catalog_idempotency_ledger ENABLE ROW LEVEL SECURITY;
+ALTER TABLE catalog_idempotency_ledger FORCE ROW LEVEL SECURITY;
+CREATE POLICY catalog_idempotency_ledger_tenant_policy ON catalog_idempotency_ledger
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));

package/.ai/references/catalog/migrations/README.md

@@ -0,0 +1,3 @@
+# Migrations
+
+Migrations in this directory are append-only after release.

package/.ai/references/catalog/module.json

@@ -0,0 +1,27 @@
+{
+	"$schema": "../../packages/contracts/schemas/module.schema.json",
+	"schemaVersion": 1,
+	"id": "catalog.core",
+	"package": "@flowdular/module-catalog",
+	"version": "0.6.1",
+	"profile": "full",
+	"capabilities": ["api", "database", "client", "translations"],
+	"platform": {
+		"server": true,
+		"client": true
+	},
+	"dependencies": [
+		{
+			"id": "system.core",
+			"range": "0.5.0"
+		},
+		{
+			"id": "auth.core",
+			"range": "0.10.0"
+		}
+	],
+	"tenancy": "required",
+	"locales": ["en", "pl"],
+	"stability": "experimental",
+	"platformApi": "0.1.0"
+}

package/.ai/references/catalog/package.json

@@ -0,0 +1,49 @@
+{
+	"name": "@flowdular/module-catalog",
+	"version": "0.6.1",
+	"type": "module",
+	"exports": {
+		".": "./src/index.ts",
+		"./client": "./src/client/index.ts",
+		"./server": "./src/server/index.ts",
+		"./platform": "./src/platform.ts",
+		"./module.json": "./module.json"
+	},
+	"scripts": {
+		"typecheck": "tsrx-tsc --noEmit -p tsconfig.json",
+		"test": "vitest run"
+	},
+	"dependencies": {
+		"octane": "0.1.51",
+		"segment-state": "0.2.0",
+		"@flowdular/sdk": "0.1.0"
+	},
+	"devDependencies": {
+		"@tsrx/typescript-plugin": "0.3.120",
+		"@types/node": "24.13.3",
+		"typescript": "5.9.3",
+		"vitest": "4.1.10"
+	},
+	"license": "MIT",
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Flowdular/official-modules.git",
+		"directory": "modules/catalog"
+	},
+	"files": [
+		"src",
+		"schemas",
+		"dist",
+		"bin",
+		"public",
+		"module.json",
+		"migrations",
+		"translations",
+		"spec",
+		"README.md",
+		"LICENSE"
+	]
+}

package/.ai/references/catalog/spec/module.yaml

@@ -0,0 +1,86 @@
+schemaVersion: 1
+id: catalog.core
+specVersion: 0.6.1
+status: approved
+name: Product Catalog Core
+description: Provides tenant-scoped products and services with stable SKUs, units, prices, currencies, and lifecycle state.
+profile: full
+capabilities:
+  - api
+  - database
+  - client
+  - translations
+dependencies:
+  - id: system.core
+    range: 0.5.0
+  - id: auth.core
+    range: 0.10.0
+tenancy: required
+locales:
+  - en
+  - pl
+invariants:
+  - Persistence runs on the shared asynchronous database contract. The module receives a leased PostgreSQL handle from platform composition, never a driver or a connection string, and declares explicit PostgreSQL SQL for every statement and migration.
+  - PostgreSQL item, history, and idempotency ledger tables enable and force row-level security with USING and WITH CHECK policies bound to transaction-local coreloom.tenant_id, and the runtime role holds neither SUPERUSER nor BYPASSRLS. Migrations use a separate lease.
+  - Every catalog item is owned by exactly one tenant and every query uses the trusted tenant identifier.
+  - SKU is unique inside a tenant and is never used as tenancy authority.
+  - Monetary values are stored as integer minor units with an explicit ISO currency code.
+  - Item kind is product or service and status is active or archived.
+  - Background workflow actions preserve their service actor and the configuring user in record history.
+  - One tenant-scoped durable target ledger is shared by mutating agent tools and workflow actions; each entry binds an idempotency key to the exact tool identifier or versioned workflow action identifier, canonical input digest, and first persisted result in the same transaction as the catalog mutation.
+  - Replaying the same idempotency key for the same operation and canonical input returns the original result without another catalog item or history row, while reuse for another operation or input fails with a stable conflict.
+  - Idempotency ledger entries remain after a catalog item is deleted, and audit metadata records identifiers, input digests, and outcomes without raw tool input, credentials, secrets, or result payloads.
+permissions:
+  - id: catalog.items.read
+    description: Read products and services in the active tenant.
+  - id: catalog.items.manage
+    description: Create and update products and services in the active tenant.
+dataOwnership:
+  - catalog.core owns SKU, item identity, kind, unit, base price, currency, and lifecycle status.
+  - catalog.core owns the idempotency ledger for its mutating agent tools and workflow actions; callers supply the key but do not maintain a second target ledger.
+  - Sales and purchasing modules reference catalog item identifiers and snapshot commercial terms when required by their specs.
+acceptanceScenarios:
+  - id: CATALOG-LIST
+    given: Tenant-scoped products and services exist.
+    when: An authorized principal lists catalog items.
+    then: Only items owned by the active tenant are returned in deterministic SKU order.
+  - id: CATALOG-CREATE
+    given: An authorized principal supplies a unique SKU and valid product or service data.
+    when: The catalog item is created.
+    then: A tenant-owned active item is persisted with integer minor-unit pricing.
+  - id: CATALOG-DUPLICATE
+    given: An item already uses a SKU in the active tenant.
+    when: Another item is created with the same normalized SKU.
+    then: The server returns a stable conflict error and leaves existing data unchanged.
+  - id: CATALOG-DENY
+    given: A principal is unauthenticated or lacks the required catalog permission.
+    when: The principal reads or mutates catalog data.
+    then: The server denies the operation before repository access.
+  - id: CATALOG-AGENT-TOOL
+    given: An agent run holds catalog.items.manage in its permission snapshot and the tool catalog.item.create in its grants.
+    when: The agent invokes the tool with a valid item, and a run without the manage scope invokes the same tool.
+    then: The scoped run creates a tenant-owned catalog item from the run tenant and the harness denies the unscoped run before any write.
+  - id: CATALOG-LIFECYCLE-HISTORY
+    given: A catalog item is active in the current tenant.
+    when: An authorized principal edits it, archives it, restores it, or deletes it after archiving.
+    then: Each accepted transition has an append-only tenant-scoped revision with the user or agent actor, and the item history endpoint returns only that tenant's revisions.
+  - id: CATALOG-WORKFLOW-ACTIONS
+    given: A workflow revision selects a versioned catalog read or create action and carries the matching permission snapshot.
+    when: The action capability validates and executes the node with an idempotency key and service actor.
+    then: The action exposes exact input and output schemas, refuses a missing permission before work, cooperates with cancellation, and attributes a created item to the service and its configuring user.
+  - id: CATALOG-IDEMPOTENCY-REPLAY
+    given: A mutating catalog tool or workflow action has committed a catalog mutation and its target-ledger result for an idempotency key.
+    when: The caller repeats the exact operation with the same canonical input and key, including after losing the first response.
+    then: The module returns the original persisted result and creates no second catalog item or history row.
+  - id: CATALOG-IDEMPOTENCY-CONFLICT
+    given: A tenant-scoped idempotency key is already bound to an exact catalog tool identifier or versioned workflow action identifier and canonical input digest.
+    when: A caller reuses the key for a different operation or canonical input.
+    then: The module returns a stable conflict before any catalog item, history, or ledger write.
+  - id: CATALOG-POSTGRESQL-TENANT-BOUNDARY
+    given: catalog.core runs on PostgreSQL and two tenants own catalog data.
+    when: A runtime transaction bound to one tenant reads or writes items, history, or ledger rows.
+    then: Only that tenant's rows are visible or mutable, a transaction without a tenant is refused, and the forced row-level security policy rejects a row carrying another tenant identifier.
+  - id: CATALOG-IDEMPOTENCY-RECOVERY
+    given: A catalog item has been committed atomically with its idempotency result, or the item is later deleted through its lifecycle operation.
+    when: Recovery replays the mutating tool or workflow action with the same key.
+    then: The retained ledger returns the original result without another mutation, and audit evidence contains no raw input, credentials, secrets, or result payload.

package/.ai/references/catalog/src/acl/permissions.ts

@@ -0,0 +1,6 @@
+export const CATALOG_PERMISSIONS = {
+	read: 'catalog.items.read',
+	manage: 'catalog.items.manage',
+} as const;
+
+export const permissions = Object.freeze(Object.values(CATALOG_PERMISSIONS));

package/.ai/references/catalog/src/agent/tools.ts

@@ -0,0 +1,164 @@
+import { defineApiAgentTool } from '@flowdular/sdk/harness/tool-adapters';
+import {
+	AgentHarnessError,
+	type AgentTool,
+	type AgentToolContext,
+} from '@flowdular/sdk/harness/runtime';
+import { agentActor, type Actor } from '@flowdular/sdk/kernel';
+import { CATALOG_PERMISSIONS } from '../acl/permissions.ts';
+import type { CatalogItemKind } from '../domain/types.ts';
+import type { CatalogRuntime } from '../server/runtime.ts';
+import { CatalogServiceError } from '../services/catalog-service.ts';
+
+const MAX_TOOL_ROWS = 200;
+const CREATE_OPERATION = 'catalog.item.create@1';
+
+const CATALOG_ITEM_OUTPUT_SCHEMA = {
+	type: 'object',
+	additionalProperties: false,
+	required: [
+		'id',
+		'tenantId',
+		'sku',
+		'name',
+		'kind',
+		'unit',
+		'basePriceMinor',
+		'currency',
+		'status',
+		'createdAt',
+	],
+	properties: {
+		id: { type: 'string' },
+		tenantId: { type: 'string' },
+		sku: { type: 'string' },
+		name: { type: 'string' },
+		kind: { type: 'string', enum: ['product', 'service'] },
+		unit: { type: 'string' },
+		basePriceMinor: { type: 'integer' },
+		currency: { type: 'string' },
+		status: { type: 'string', enum: ['active', 'archived'] },
+		createdAt: { type: 'integer' },
+	},
+} as const;
+
+function actionActor(context: AgentToolContext): Actor {
+	return context.actor ?? agentActor(context);
+}
+
+function normalized(value: unknown): string {
+	return typeof value === 'string'
+		? value.trim().toLocaleLowerCase('en-US')
+		: '';
+}
+
+function idempotencyKey(context: AgentToolContext): string {
+	if (!context.idempotencyKey) {
+		throw new AgentHarnessError(
+			'TOOL_IDEMPOTENCY_KEY_REQUIRED',
+			'The catalog create tool requires a durable idempotency key.',
+		);
+	}
+	return context.idempotencyKey;
+}
+
+/* Tools call the catalog service and take the tenant and the actor from the
+   run context, never from input; the service revalidates so a tool cannot
+   bypass the endpoint's rules, every write is attributed to the run that made
+   it, and list output is capped so one call cannot flood the run window. */
+export function catalogAgentTools(
+	runtime: CatalogRuntime,
+): readonly AgentTool[] {
+	return [
+		defineApiAgentTool({
+			id: 'catalog.item.list',
+			endpointId: 'catalog.items.list',
+			contractVersion: 1,
+			description:
+				'List products and services of the active tenant, optionally filtered by a free-text query.',
+			requiredPermissions: [CATALOG_PERMISSIONS.read],
+			risk: 'read',
+			idempotency: 'required',
+			cancellation: 'cooperative',
+			inputSchema: {
+				type: 'object',
+				additionalProperties: false,
+				properties: { query: { type: 'string', maxLength: 120 } },
+			},
+			outputSchema: { type: 'array', items: CATALOG_ITEM_OUTPUT_SCHEMA },
+			execute: async (input, context) => {
+				context.signal.throwIfAborted();
+				const query = normalized(
+					(input as Record<string, unknown> | null)?.query,
+				);
+				return (await (await runtime.service()).list(context.tenantId))
+					.filter(
+						(item) =>
+							query === '' ||
+							item.id.toLocaleLowerCase('en-US') === query ||
+							item.sku.toLocaleLowerCase('en-US').includes(query) ||
+							item.name.toLocaleLowerCase('en-US').includes(query),
+					)
+					.slice(0, MAX_TOOL_ROWS);
+			},
+		}),
+		defineApiAgentTool({
+			id: 'catalog.item.create',
+			endpointId: 'catalog.items.create',
+			contractVersion: 1,
+			description: 'Create a product or service owned by the active tenant.',
+			requiredPermissions: [CATALOG_PERMISSIONS.manage],
+			risk: 'workspace-write',
+			idempotency: 'required',
+			idempotencyProtection: 'target-ledger',
+			cancellation: 'cooperative',
+			inputSchema: {
+				type: 'object',
+				additionalProperties: false,
+				required: ['sku', 'name', 'kind', 'unit', 'basePriceMinor', 'currency'],
+				properties: {
+					sku: { type: 'string', maxLength: 64 },
+					name: { type: 'string', maxLength: 160 },
+					kind: { type: 'string', enum: ['product', 'service'] },
+					unit: { type: 'string', maxLength: 24 },
+					basePriceMinor: { type: 'integer' },
+					currency: { type: 'string', maxLength: 3 },
+				},
+			},
+			outputSchema: CATALOG_ITEM_OUTPUT_SCHEMA,
+			execute: async (input, context) => {
+				context.signal.throwIfAborted();
+				const value = (input ?? {}) as Record<string, unknown>;
+				try {
+					return (await runtime.service()).createIdempotent(
+						context.tenantId,
+						{
+							sku: String(value.sku ?? ''),
+							name: String(value.name ?? ''),
+							kind: value.kind as CatalogItemKind,
+							unit: String(value.unit ?? ''),
+							basePriceMinor:
+								typeof value.basePriceMinor === 'number'
+									? value.basePriceMinor
+									: Number.NaN,
+							currency: String(value.currency ?? ''),
+						},
+						actionActor(context),
+						{
+							key: idempotencyKey(context),
+							operationId: CREATE_OPERATION,
+						},
+					);
+				} catch (error) {
+					if (
+						error instanceof CatalogServiceError &&
+						error.code === 'CATALOG_IDEMPOTENCY_CONFLICT'
+					) {
+						throw new AgentHarnessError(error.code, error.message);
+					}
+					throw error;
+				}
+			},
+		}),
+	];
+}

package/.ai/references/catalog/src/api/endpoints.ts

@@ -0,0 +1,243 @@
+import {
+	defineEndpoint,
+	HttpProblem,
+	jsonResponse,
+	problemResponse,
+	readJsonObject,
+	requiredInteger,
+	requiredString,
+} from '@flowdular/sdk/server';
+import { parseHistoryRequest } from '@flowdular/sdk/kernel';
+import type { AuthRuntime } from '@flowdular/sdk/modules/auth/server';
+import {
+	actorFromContext,
+	endpointIdentityFromContext,
+	principalFromContext,
+	sessionMutationDenial,
+} from '@flowdular/sdk/modules/auth/server';
+import { CATALOG_PERMISSIONS } from '../acl/permissions.ts';
+import type {
+	CatalogItemKind,
+	CreateCatalogItemInput,
+	UpdateCatalogItemInput,
+} from '../domain/types.ts';
+import { CatalogServiceError } from '../services/catalog-service.ts';
+import type { CatalogRuntime } from '../server/runtime.ts';
+
+function failure(error: unknown): Response {
+	if (error instanceof CatalogServiceError) {
+		return jsonResponse(
+			{ error: { code: error.code, message: error.message } },
+			error.status,
+		);
+	}
+	return problemResponse(error, 'The catalog operation failed.');
+}
+
+function mutableInput(
+	value: Record<string, unknown>,
+): Omit<UpdateCatalogItemInput, 'id'> {
+	const kind = requiredString(value, 'kind');
+	if (kind !== 'product' && kind !== 'service') {
+		throw new HttpProblem(
+			'INVALID_ITEM_KIND',
+			'kind must be product or service.',
+			400,
+		);
+	}
+	return {
+		name: requiredString(value, 'name', { min: 2, max: 160 }),
+		kind: kind as CatalogItemKind,
+		unit: requiredString(value, 'unit', { max: 24 }),
+		basePriceMinor: requiredInteger(value, 'basePriceMinor', { min: 0 }),
+		currency: requiredString(value, 'currency', { min: 3, max: 3 }),
+	};
+}
+
+export function createCatalogRoutes(
+	auth: AuthRuntime,
+	runtime: CatalogRuntime,
+) {
+	const list = defineEndpoint({
+		id: 'catalog.items.list',
+		path: '/api/catalog/items',
+		methods: ['GET'],
+		access: { kind: 'permission', permission: CATALOG_PERMISSIONS.read },
+		resolveIdentity: endpointIdentityFromContext,
+		handler: async ({ octane }) =>
+			jsonResponse({
+				items: await (
+					await runtime.service()
+				).list(principalFromContext(octane)!.tenantId),
+			}),
+	});
+	const create = defineEndpoint({
+		id: 'catalog.items.create',
+		path: '/api/catalog/items',
+		methods: ['POST'],
+		access: { kind: 'permission', permission: CATALOG_PERMISSIONS.manage },
+		resolveIdentity: endpointIdentityFromContext,
+		handler: async ({ octane }) => {
+			const denial = sessionMutationDenial(octane, auth);
+			if (denial) return denial;
+			try {
+				const service = await runtime.service();
+				const value = await readJsonObject(octane.request);
+				const mutable = mutableInput(value);
+				const input: CreateCatalogItemInput = {
+					sku: requiredString(value, 'sku', { max: 64 }),
+					...mutable,
+				};
+				return jsonResponse(
+					{
+						item: await service.create(
+							principalFromContext(octane)!.tenantId,
+							input,
+							actorFromContext(octane)!,
+						),
+					},
+					201,
+				);
+			} catch (error) {
+				return failure(error);
+			}
+		},
+	});
+	const update = defineEndpoint({
+		id: 'catalog.items.update',
+		path: '/api/catalog/items/update',
+		methods: ['POST'],
+		access: { kind: 'permission', permission: CATALOG_PERMISSIONS.manage },
+		resolveIdentity: endpointIdentityFromContext,
+		handler: async ({ octane }) => {
+			const denial = sessionMutationDenial(octane, auth);
+			if (denial) return denial;
+			try {
+				const service = await runtime.service();
+				const value = await readJsonObject(octane.request);
+				return jsonResponse({
+					item: await service.update(
+						principalFromContext(octane)!.tenantId,
+						{
+							id: requiredString(value, 'id', { max: 128 }),
+							...mutableInput(value),
+						},
+						actorFromContext(octane)!,
+					),
+				});
+			} catch (error) {
+				return failure(error);
+			}
+		},
+	});
+	const lifecycle = (action: 'archive' | 'restore', path: string, id: string) =>
+		defineEndpoint({
+			id,
+			path,
+			methods: ['POST'],
+			access: { kind: 'permission', permission: CATALOG_PERMISSIONS.manage },
+			resolveIdentity: endpointIdentityFromContext,
+			handler: async ({ octane }) => {
+				const denial = sessionMutationDenial(octane, auth);
+				if (denial) return denial;
+				try {
+					const value = await readJsonObject(octane.request);
+					const service = await runtime.service();
+					const item = await service[action](
+						principalFromContext(octane)!.tenantId,
+						requiredString(value, 'id', { max: 128 }),
+						actorFromContext(octane)!,
+					);
+					return jsonResponse({ item });
+				} catch (error) {
+					return failure(error);
+				}
+			},
+		});
+	const archive = lifecycle(
+		'archive',
+		'/api/catalog/items/archive',
+		'catalog.items.archive',
+	);
+	const restore = lifecycle(
+		'restore',
+		'/api/catalog/items/restore',
+		'catalog.items.restore',
+	);
+	const remove = defineEndpoint({
+		id: 'catalog.items.delete',
+		path: '/api/catalog/items/delete',
+		methods: ['POST'],
+		access: { kind: 'permission', permission: CATALOG_PERMISSIONS.manage },
+		resolveIdentity: endpointIdentityFromContext,
+		handler: async ({ octane }) => {
+			const denial = sessionMutationDenial(octane, auth);
+			if (denial) return denial;
+			try {
+				const service = await runtime.service();
+				const value = await readJsonObject(octane.request);
+				await service.delete(
+					principalFromContext(octane)!.tenantId,
+					requiredString(value, 'id', { max: 128 }),
+					actorFromContext(octane)!,
+				);
+				return jsonResponse({ deleted: true });
+			} catch (error) {
+				return failure(error);
+			}
+		},
+	});
+	const history = defineEndpoint({
+		id: 'catalog.items.history',
+		path: '/api/catalog/items/history',
+		methods: ['GET'],
+		access: { kind: 'permission', permission: CATALOG_PERMISSIONS.read },
+		resolveIdentity: endpointIdentityFromContext,
+		handler: async ({ octane }) => {
+			const request = parseHistoryRequest(
+				new URL(octane.request.url).searchParams,
+			);
+			if (!request) {
+				return jsonResponse(
+					{
+						error: {
+							code: 'INVALID_INPUT',
+							message: 'recordId is required.',
+						},
+					},
+					400,
+				);
+			}
+			try {
+				const service = await runtime.service();
+				return jsonResponse(
+					await service.history(
+						principalFromContext(octane)!.tenantId,
+						request,
+					),
+				);
+			} catch (error) {
+				return failure(error);
+			}
+		},
+	});
+	return [
+		list.serverRoute,
+		create.serverRoute,
+		update.serverRoute,
+		archive.serverRoute,
+		restore.serverRoute,
+		remove.serverRoute,
+		history.serverRoute,
+	] as const;
+}
+
+export const endpoints = [
+	'catalog.items.list',
+	'catalog.items.create',
+	'catalog.items.update',
+	'catalog.items.archive',
+	'catalog.items.restore',
+	'catalog.items.delete',
+	'catalog.items.history',
+] as const;