@feltdb/core 0.7.4 → 0.8.1

package/dist/module.js

@@ -0,0 +1,566 @@
+const model = (name, ownership = "external-authoritative") => ({
+    name,
+    authority: "external",
+    ownership,
+    fields: [
+        {
+            name: "id",
+            type: "text",
+            immutable: true,
+            externally_owned: true,
+            application_readable: true,
+        },
+        {
+            name: "status",
+            type: "text",
+            optional: true,
+            externally_owned: true,
+            application_readable: true,
+        },
+        {
+            name: "created_at",
+            type: "datetime",
+            externally_owned: true,
+            application_readable: true,
+        },
+        {
+            name: "metadata",
+            type: "json",
+            optional: true,
+            externally_owned: true,
+            application_readable: true,
+        },
+    ],
+});
+const stripe = {
+    id: "stripe",
+    name: "Stripe-compatible billing",
+    version: "1.0.0",
+    provider: "stripe-compatible",
+    compatibility: ["stripe", "stripe-compatible"],
+    intent_keywords: ["stripe", "billing", "plan", "subscription"],
+    models: [
+        "Customer",
+        "Product",
+        "Price",
+        "Subscription",
+        "SubscriptionItem",
+        "Invoice",
+        "PaymentIntent",
+        "CheckoutSession",
+        "PaymentMethod",
+        "Refund",
+        "WebhookEvent",
+    ].map((name) => model(name)),
+    relationships: [
+        { from: "Customer", to: "Subscription", kind: "many" },
+        { from: "Subscription", to: "SubscriptionItem", kind: "many" },
+        { from: "SubscriptionItem", to: "Price", kind: "one" },
+        { from: "Price", to: "Product", kind: "one" },
+        { from: "Customer", to: "Invoice", kind: "many" },
+        { from: "Invoice", to: "PaymentIntent", kind: "one" },
+    ],
+    events: [
+        "stripe.customer.created",
+        "stripe.customer.updated",
+        "stripe.subscription.created",
+        "stripe.subscription.updated",
+        "stripe.subscription.deleted",
+        "stripe.invoice.paid",
+        "stripe.invoice.payment_failed",
+        "stripe.checkout.session.completed",
+    ],
+    capabilities: [
+        "stripe.customer.read",
+        "stripe.customer.create",
+        "stripe.checkout.create",
+        "stripe.subscription.read",
+        "stripe.subscription.create",
+        "stripe.subscription.cancel",
+        "stripe.invoice.read",
+        "stripe.webhooks.receive",
+    ],
+    workflows: ["ReconcileSubscription", "ReconcileFailedPayment"],
+    configuration: [
+        {
+            name: "STRIPE_PUBLISHABLE_KEY",
+            required: false,
+            description: "Browser-safe publishable provider key",
+            visibility: "browser",
+        },
+    ],
+    secrets: [
+        {
+            name: "STRIPE_SECRET_KEY",
+            required: true,
+            description: "Server-side provider credential",
+            visibility: "server",
+        },
+        {
+            name: "STRIPE_WEBHOOK_SECRET",
+            required: true,
+            environments: ["production"],
+            description: "Webhook signature verification secret",
+            visibility: "server",
+        },
+    ],
+    validation: [
+        "Webhook receivers must verify signatures",
+        "Checkout creation requires authenticated authorization",
+    ],
+    dependencies: [
+        {
+            name: "authentication",
+            description: "Checkout requires an authenticated application identity",
+            any_collections: ["User", "Account"],
+            any_capabilities: ["auth.session.read", "authentication"],
+        },
+    ],
+    authorization: [
+        {
+            capability: "stripe.checkout.create",
+            subject: "authenticated",
+            implication: "A signed-in billing owner may create a hosted checkout session",
+        },
+        {
+            capability: "stripe.subscription.cancel",
+            subject: "owner",
+            implication: "Only the billing owner may cancel a subscription",
+        },
+    ],
+    extension_application_models: [
+        {
+            name: "BillingPlan",
+            ownership: "application-authoritative",
+            purpose: "Application pricing and entitlement plan",
+            fields: [
+                { name: "code", type: "text" },
+                { name: "interval", type: "enum(monthly,annual)" },
+                { name: "price", type: "ref $module.Price" },
+                { name: "active", type: "boolean" },
+            ],
+        },
+    ],
+    patterns: [
+        {
+            name: "organization billing",
+            when: "The application contains an organizational owner",
+            owner_candidates: ["Organization", "Workspace"],
+            application_models: [
+                {
+                    name: "BillingAccount",
+                    ownership: "application-authoritative",
+                    purpose: "Connect the application billing owner to provider state",
+                    fields: [
+                        { name: "owner", type: "ref $owner" },
+                        { name: "customer", type: "ref $module.Customer" },
+                        {
+                            name: "subscription",
+                            type: "ref $module.Subscription",
+                            optional: true,
+                        },
+                        { name: "status", type: "text" },
+                    ],
+                },
+                {
+                    name: "Entitlement",
+                    ownership: "derived",
+                    purpose: "Materialize product access from reconciled subscription state",
+                    fields: [
+                        { name: "billing_account", type: "ref BillingAccount" },
+                        { name: "key", type: "text" },
+                        { name: "active", type: "boolean" },
+                    ],
+                },
+            ],
+        },
+        {
+            name: "user billing",
+            when: "The application is user-centric",
+            owner_candidates: ["User", "Account"],
+            application_models: [
+                {
+                    name: "BillingAccount",
+                    ownership: "application-authoritative",
+                    purpose: "Connect the user to provider state",
+                    fields: [
+                        { name: "owner", type: "ref $owner" },
+                        { name: "customer", type: "ref $module.Customer" },
+                        {
+                            name: "subscription",
+                            type: "ref $module.Subscription",
+                            optional: true,
+                        },
+                        { name: "status", type: "text" },
+                    ],
+                },
+                {
+                    name: "Entitlement",
+                    ownership: "derived",
+                    purpose: "Materialize product access from reconciled subscription state",
+                    fields: [
+                        { name: "billing_account", type: "ref BillingAccount" },
+                        { name: "key", type: "text" },
+                        { name: "active", type: "boolean" },
+                    ],
+                },
+            ],
+        },
+    ],
+    reconciliation: [
+        {
+            event: "stripe.subscription.updated",
+            workflow: "ReconcileSubscription",
+            reads: ["stripe.Subscription", "BillingAccount"],
+            writes: ["BillingAccount", "Entitlement"],
+            outcome: "Subscription changes become application entitlements",
+        },
+        {
+            event: "stripe.invoice.payment_failed",
+            workflow: "ReconcileFailedPayment",
+            reads: ["stripe.Invoice", "BillingAccount"],
+            writes: ["BillingAccount", "Entitlement"],
+            outcome: "Failed payment state restricts derived entitlements",
+        },
+    ],
+    placement: {
+        owner_claim: "billing.owner",
+        primary_application_model: "BillingAccount",
+        owner_field: "owner",
+    },
+    source_artifacts: [
+        {
+            path: "src/integrations/stripe/domain.ts",
+            role: "module-domain",
+            purpose: "Application billing state",
+        },
+        {
+            path: "src/integrations/stripe/provider-boundary.ts",
+            role: "module-provider-boundary",
+            purpose: "Stripe operations and verified event boundary",
+        },
+        {
+            path: "src/integrations/stripe/reconcile.ts",
+            role: "module-reconciliation",
+            purpose: "Subscription to entitlement reconciliation",
+        },
+        {
+            path: "src/integrations/stripe/IntegrationView.tsx",
+            role: "module-ui",
+            purpose: "Billing application experience",
+        },
+        {
+            path: "src/integrations/stripe/module.test.ts",
+            role: "module-contract-test",
+            purpose: "Module contract test",
+        },
+    ],
+};
+const github = {
+    id: "github",
+    name: "GitHub App collaboration",
+    version: "1.0.0",
+    provider: "github-app",
+    compatibility: ["github", "github-app"],
+    intent_keywords: ["github", "repository", "repositories", "issues"],
+    models: [
+        model("Organization"),
+        model("Repository"),
+        model("Installation", "synchronized"),
+        model("Issue"),
+        model("Membership"),
+    ],
+    relationships: [
+        { from: "Organization", to: "Repository", kind: "many" },
+        { from: "Installation", to: "Repository", kind: "many" },
+        { from: "Repository", to: "Issue", kind: "many" },
+    ],
+    events: [
+        "github.repository.created",
+        "github.repository.updated",
+        "github.repository.deleted",
+        "github.installation.created",
+        "github.installation.deleted",
+        "github.membership.added",
+        "github.membership.removed",
+    ],
+    capabilities: [
+        "github.repository.read",
+        "github.repository.create",
+        "github.issue.read",
+        "github.issue.write",
+        "github.webhooks.receive",
+    ],
+    workflows: ["SynchronizeRepository", "SynchronizeInstallation"],
+    configuration: [
+        {
+            name: "GITHUB_APP_ID",
+            required: true,
+            description: "GitHub App identifier",
+            visibility: "server",
+        },
+    ],
+    secrets: [
+        {
+            name: "GITHUB_PRIVATE_KEY",
+            required: true,
+            description: "GitHub App signing key",
+            visibility: "server",
+        },
+        {
+            name: "GITHUB_WEBHOOK_SECRET",
+            required: true,
+            description: "GitHub webhook verification secret",
+            visibility: "server",
+        },
+    ],
+    validation: [
+        "Webhook receivers must verify signatures",
+        "Repository writes require explicit application authorization",
+    ],
+    dependencies: [
+        {
+            name: "authentication",
+            description: "GitHub installation management requires authenticated identity",
+            any_collections: ["User", "Account"],
+            any_capabilities: ["auth.session.read", "authentication"],
+        },
+    ],
+    authorization: [
+        {
+            capability: "github.repository.read",
+            subject: "authenticated",
+            implication: "Authenticated members may read connected repositories",
+        },
+        {
+            capability: "github.repository.create",
+            subject: "owner",
+            implication: "The integration owner controls repository creation",
+        },
+    ],
+    patterns: [
+        {
+            name: "organizational collaboration",
+            when: "Projects belong to an organization or workspace",
+            owner_candidates: ["Organization", "Workspace"],
+            application_models: [
+                {
+                    name: "GitHubConnection",
+                    ownership: "application-authoritative",
+                    purpose: "Bind an application owner to a GitHub App installation",
+                    fields: [
+                        { name: "owner", type: "ref $owner" },
+                        { name: "installation", type: "ref $module.Installation" },
+                        { name: "status", type: "text" },
+                    ],
+                },
+                {
+                    name: "RepositoryConnection",
+                    ownership: "synchronized",
+                    purpose: "Map provider repositories into application projects",
+                    fields: [
+                        { name: "connection", type: "ref GitHubConnection" },
+                        { name: "repository", type: "ref $module.Repository" },
+                        { name: "project", type: "ref $project", optional: true },
+                        { name: "synchronized_at", type: "datetime" },
+                    ],
+                },
+            ],
+        },
+        {
+            name: "personal collaboration",
+            when: "Projects belong directly to a user",
+            owner_candidates: ["User", "Account"],
+            application_models: [
+                {
+                    name: "GitHubConnection",
+                    ownership: "application-authoritative",
+                    purpose: "Bind a user to a GitHub App installation",
+                    fields: [
+                        { name: "owner", type: "ref $owner" },
+                        { name: "installation", type: "ref $module.Installation" },
+                        { name: "status", type: "text" },
+                    ],
+                },
+                {
+                    name: "RepositoryConnection",
+                    ownership: "synchronized",
+                    purpose: "Map provider repositories into application projects",
+                    fields: [
+                        { name: "connection", type: "ref GitHubConnection" },
+                        { name: "repository", type: "ref $module.Repository" },
+                        { name: "project", type: "ref $project", optional: true },
+                        { name: "synchronized_at", type: "datetime" },
+                    ],
+                },
+            ],
+        },
+    ],
+    reconciliation: [
+        {
+            event: "github.repository.updated",
+            workflow: "SynchronizeRepository",
+            reads: ["github.Repository", "RepositoryConnection"],
+            writes: ["RepositoryConnection"],
+            outcome: "Repository changes synchronize into application project state",
+        },
+        {
+            event: "github.installation.created",
+            workflow: "SynchronizeInstallation",
+            reads: ["github.Installation"],
+            writes: ["GitHubConnection"],
+            outcome: "GitHub App installations become application connections",
+        },
+    ],
+    placement: {
+        owner_claim: "repository.owner",
+        primary_application_model: "GitHubConnection",
+        owner_field: "owner",
+    },
+    source_artifacts: [
+        {
+            path: "src/integrations/github/domain.ts",
+            role: "module-domain",
+            purpose: "GitHub connection state",
+        },
+        {
+            path: "src/integrations/github/provider-boundary.ts",
+            role: "module-provider-boundary",
+            purpose: "GitHub App operations and webhook verification",
+        },
+        {
+            path: "src/integrations/github/reconcile.ts",
+            role: "module-reconciliation",
+            purpose: "Repository synchronization",
+        },
+        {
+            path: "src/integrations/github/IntegrationView.tsx",
+            role: "module-ui",
+            purpose: "Repository connection experience",
+        },
+        {
+            path: "src/integrations/github/module.test.ts",
+            role: "module-contract-test",
+            purpose: "Module contract test",
+        },
+    ],
+};
+const definitions = new Map();
+export function validateFeltDBModule(module) {
+    const errors = [];
+    for (const key of ["id", "name", "version", "provider"])
+        if (!module[key])
+            errors.push(`missing:${key}`);
+    for (const name of [
+        "compatibility",
+        "models",
+        "relationships",
+        "events",
+        "workflows",
+        "capabilities",
+        "configuration",
+        "secrets",
+        "authorization",
+        "dependencies",
+        "patterns",
+        "reconciliation",
+        "source_artifacts",
+    ])
+        if (!Array.isArray(module[name]))
+            errors.push(`missing:${name}`);
+    for (const item of module.models ?? [])
+        if (![
+            "external-authoritative",
+            "application-authoritative",
+            "derived",
+            "synchronized",
+        ].includes(item.ownership))
+            errors.push(`invalid_ownership:${item.name}`);
+    if (!module.placement?.owner_claim ||
+        !module.placement?.primary_application_model ||
+        !module.placement?.owner_field)
+        errors.push("missing:placement");
+    for (const pattern of module.patterns ?? [])
+        for (const applicationModel of pattern.application_models)
+            if (!applicationModel.fields?.length)
+                errors.push(`missing_fields:${applicationModel.name}`);
+    const modelNames = new Set((module.models ?? []).map(value => value.name));
+    for (const relationship of module.relationships ?? []) {
+        if (!modelNames.has(relationship.from))
+            errors.push(`unknown_relationship_model:${relationship.from}`);
+        if (!modelNames.has(relationship.to))
+            errors.push(`unknown_relationship_model:${relationship.to}`);
+    }
+    const events = new Set(module.events ?? []);
+    const workflows = new Set(module.workflows ?? []);
+    const capabilities = new Set(module.capabilities ?? []);
+    for (const reconciliation of module.reconciliation ?? []) {
+        if (!events.has(reconciliation.event))
+            errors.push(`undeclared_reconciliation_event:${reconciliation.event}`);
+        if (!workflows.has(reconciliation.workflow))
+            errors.push(`undeclared_reconciliation_workflow:${reconciliation.workflow}`);
+    }
+    for (const authorization of module.authorization ?? [])
+        if (!capabilities.has(authorization.capability))
+            errors.push(`undeclared_authorization_capability:${authorization.capability}`);
+    for (const secret of module.secrets ?? [])
+        if (secret.visibility === 'browser' || secret.name.startsWith('VITE_'))
+            errors.push(`browser_secret:${secret.name}`);
+    const sourceRoles = new Set(['module-domain', 'module-provider-boundary', 'module-reconciliation', 'module-ui', 'module-contract-test']);
+    for (const artifact of module.source_artifacts ?? [])
+        if (!artifact.path.startsWith(`src/integrations/${module.id}/`) || !sourceRoles.has(artifact.role))
+            errors.push(`invalid_source_artifact:${artifact.path}`);
+    return [...new Set(errors)];
+}
+export function registerFeltDBModule(module) {
+    const errors = validateFeltDBModule(module);
+    if (errors.length)
+        throw new Error(`MODULE_CONFORMANCE_FAILED: ${errors.join(", ")}`);
+    if (definitions.has(module.id))
+        throw new Error(`MODULE_ALREADY_REGISTERED: ${module.id}`);
+    definitions.set(module.id, structuredClone(module));
+    return () => {
+        definitions.delete(module.id);
+    };
+}
+registerFeltDBModule(stripe);
+registerFeltDBModule(github);
+export function listFeltDBModules() {
+    return [...definitions.values()]
+        .map((value) => structuredClone(value))
+        .sort((a, b) => a.id.localeCompare(b.id));
+}
+export function resolveFeltDBModule(declaration) {
+    const definition = definitions.get(declaration.name);
+    if (!definition)
+        throw new Error(`UNKNOWN_MODULE: ${declaration.name}`);
+    if (!definition.compatibility.includes(declaration.provider))
+        throw new Error(`INCOMPATIBLE_MODULE_PROVIDER: ${declaration.name} does not support ${declaration.provider}`);
+    if (declaration.version && declaration.version !== definition.version)
+        throw new Error(`INCOMPATIBLE_MODULE_VERSION: ${declaration.name}@${declaration.version}; available ${definition.version}`);
+    return { ...structuredClone(definition), provider: declaration.provider };
+}
+export function findFeltDBModules(query) {
+    const normalized = query.trim().toLowerCase();
+    return listFeltDBModules().filter((module) => module.id === normalized ||
+        module.name.toLowerCase().includes(normalized) ||
+        module.compatibility.some((value) => value.includes(normalized)) ||
+        module.intent_keywords.includes(normalized));
+}
+export function resolveFeltDBModules(declarations = []) {
+    return declarations
+        .map(resolveFeltDBModule)
+        .sort((a, b) => a.id.localeCompare(b.id));
+}
+export function validateResolvedModules(modules, environment = "development") {
+    return modules.flatMap((module) => [
+        ...validateFeltDBModule(module).map((value) => `${module.id}: ${value}`),
+        ...module.secrets
+            .filter((value) => value.required &&
+            (!value.environments || value.environments.includes(environment)))
+            .map((value) => `${value.name} is required in ${environment} runtime configuration`),
+        ...module.capabilities
+            .filter((value) => value.endsWith(".create"))
+            .map((value) => `${value} requires an explicit authorization policy`),
+    ]);
+}