@avakado.ai/schemas 1.0.0

package/LICENSE

@@ -0,0 +1,7 @@
+UNLICENSED
+
+Copyright (c) Campus Root. All rights reserved.
+
+This software is proprietary. Publishing a package to the public npm registry
+does not grant a license to use, copy, modify, or redistribute it. Contact
+Campus Root for permission.

package/README.md

@@ -0,0 +1,96 @@
+# @avakado.ai/schemas
+
+The canonical Mongo schemas, models, enums and index declarations for the Avakado platform. Four
+services share one database; this package makes them share one definition of it.
+
+```bash
+npm install @avakado.ai/schemas
+```
+
+`mongoose` is a **peer** dependency (`^8.0.0`). The service owns the mongoose instance and the
+connection; this package only registers models on it.
+
+## Usage
+
+```js
+import mongoose from "mongoose";
+import { configureSchemas } from "@avakado.ai/schemas";
+import { sendKafkaMessage } from "./src/utils/kafka.js";
+
+// once, at startup, before any model method runs
+configureSchemas({ sendKafkaMessage });
+await mongoose.connect(process.env.MONGO_URI);
+```
+
+```js
+import { Business, Payment, Subscription, UsageLog, Conversation, Campaign, Task } from "@avakado.ai/schemas";
+import { SUBSCRIPTION_STATUS, CURRENT_SUBSCRIPTION_STATUSES } from "@avakado.ai/schemas/enums";
+import { Payment } from "@avakado.ai/schemas/models/Payments.js";   // narrower import, same registration
+```
+
+Every entry point returns the **same** registered model. Importing a model twice — via the barrel and
+via a subpath, or from two places in a dependency tree — reuses the existing registration instead of
+throwing `OverwriteModelError`.
+
+## What is in v1
+
+| Model | Collection | Notes |
+| --- | --- | --- |
+| `Business` | `Businesses` | `credits` is the nested canonical shape; only socketio-server writes `credits.balance` |
+| `Payment` | `Payments` | Razorpay ids live here; there is no `Invoices` collection |
+| `Subscription` | `Subscriptions` | owns the unique partial index `one_current_subscription_per_business` |
+| `UsageLog` | `UsageLogs` | the credit ledger; unique `idempotencyKey` |
+| `Conversation` | `Conversations` | includes `updateStatus`, which needs `sendKafkaMessage` |
+| `Campaign` / `Task` | `Campaign` / `Tasks` | includes `updateTimeLine`; the task executor stays in socketio-server |
+| `Trigger` | `triggers` | read by `Conversation.updateStatus` |
+
+Only models that have been through a cross-service alignment pass are here. Extracting an unaligned
+model would freeze whichever copy happened to be picked — that is exactly how production ended up
+running a partial index whose filter matched zero documents.
+
+Still per-service, pending alignment: `Agent`, `Channels`, `Workflow`, `Messages`, `Leads`,
+`CallSessions`, `Plans`, `User`, `Collection`, `Action`, `Log`, `apiAuthenticator`, `market`,
+`InbuiltNodes`, `ExternalServiceProviders`, and the already-identical-but-not-yet-moved `BillingLogs`,
+`Data`, `Document`, `Integrations`, `Job`, `Tickets`, `notifications`.
+
+## Behaviour that needs the host service
+
+A package cannot import a service's `utils/`, so anything a shared model needs is injected once via
+`configureSchemas`:
+
+| Option | Used by | If missing |
+| --- | --- | --- |
+| `sendKafkaMessage` | `Conversation.updateStatus` | throws a named error telling you to call `configureSchemas` |
+
+Methods that need more than a function — socketio-server's `Task.trigger` needs its `RealtimeServer`
+plus the `Message` and `CallSession` models — stay in the service and attach to the shared model:
+
+```js
+import { Task } from "@avakado.ai/schemas";
+Task.prototype.trigger = async function () { /* socketio-only executor */ };
+```
+
+Fields are the cross-service contract. Behaviour is a role, and roles differ: socketio-server is the
+only ledger writer, Lambda is the only service that advances campaign state.
+
+## Deliberate behaviour changes in v1
+
+- **`Conversation.updateStatus` saves before it publishes.** The per-service copies published the
+  summarisation job and the customer's workflow triggers *first*, so a status that failed validation
+  still dispatched work for a change that never persisted.
+- **`updateStatus()` with no argument throws** instead of quietly unsetting `status`.
+- **`credits.lastUpdated` defaults to `Date.now`**, not `new Date()` evaluated once at import — the
+  old form gave every document the timestamp of process start.
+
+## Index changes need a migration
+
+Mongo will not redefine an index that already exists under the same name with different options; it
+keeps the old one and the `createIndex` call fails, which `autoIndex` swallows. When an index spec in
+this package changes, each environment needs an explicit drop first:
+
+```js
+await db.collection("Subscriptions").dropIndex("one_current_subscription_per_business");
+await Subscription.createIndexes();
+```
+
+That is why an index or enum change is a major version bump.

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@avakado.ai/schemas",
+  "version": "1.0.0",
+  "description": "Canonical Mongo schemas, models, enums and index declarations shared by the Avakado services.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js",
+    "./models": "./src/models/index.js",
+    "./models/*": "./src/models/*",
+    "./enums": "./src/enums/index.js",
+    "./runtime": "./src/runtime.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "mongoose": "^8.0.0"
+  },
+  "devDependencies": {
+    "mongoose": "^8.19.2"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Campus-Root/avakado-shared.git",
+    "directory": "packages/schemas"
+  },
+  "keywords": [
+    "avakado",
+    "mongoose",
+    "schemas"
+  ]
+}

package/src/enums/index.js

@@ -0,0 +1,64 @@
+// Enums are exported on their own because more of this platform's cross-service bugs lived in enum
+// drift than in field lists: a status one service wrote and another rejected, a ledger source type
+// missing from a validator, a partial index filtering on a status list that had fallen behind.
+// Anything that validates or filters on these values must read them from here.
+
+export const SUBSCRIPTION_STATUS = [
+    "created",
+    "pending_payment",
+    "authenticated",
+    "active",
+    "pending",
+    "pending_downgrade",
+    "cancel_at_period_end",
+    "paused",
+    "halted",
+    "cancelled",
+    "expired",
+    "completed",
+];
+
+/** Statuses that make a subscription "the current one" for a business. Feeds the unique partial index. */
+export const CURRENT_SUBSCRIPTION_STATUSES = [
+    "created",
+    "pending_payment",
+    "authenticated",
+    "active",
+    "pending",
+    "pending_downgrade",
+    "cancel_at_period_end",
+    "paused",
+    "halted",
+];
+
+export const PENDING_CHANGE_TYPES = ["upgrade", "downgrade", "cancel"];
+
+export const PAYMENT_STATUS = ["authorized", "captured", "failed", "refunded"];
+
+export const LEDGER_DIRECTIONS = ["credit", "debit", "reset"];
+export const LEDGER_STATUSES = ["posted", "pending", "failed", "reversed"];
+export const LEDGER_SOURCE_TYPES = ["Message", "CallSession", "Subscription", "Payment", "Collection"];
+
+export const LEDGER_CATEGORY = {
+    PLAN_GRANT: "plan.grant",
+    TOPUP_GRANT: "topup.grant",
+    UPGRADE_GRANT: "upgrade.grant",
+    REFUND: "refund",
+    ADJUSTMENT: "adjustment",
+    AI_LLM: "ai.llm",
+    AI_TRANSCRIPTION: "ai.transcription",
+    AI_EMBEDDING: "ai.embedding",
+    MESSAGING_WHATSAPP: "messaging.whatsapp",
+    MESSAGING_SMS: "messaging.sms",
+    PLATFORM_STORAGE: "platform.storage",
+    PLATFORM_API: "platform.api",
+    THIRD_PARTY: "third_party",
+};
+
+export const CONVERSATION_STATUS = ["open", "pending", "snoozed", "completed", "closed", "archived", "spam"];
+export const CONVERSATION_PRIORITY = ["low", "normal", "high", "urgent"];
+
+export const CAMPAIGN_STATUS = ["pending", "active", "completed"];
+export const TASK_STATUS = ["pending", "in-progress", "completed", "failed", "skipped"];
+export const TASK_TYPES = ["quick", "webhook"];
+export const TASK_REFERENCE_TYPES = ["Message", "CallSession"];

package/src/index.js

@@ -0,0 +1,3 @@
+export * from "./models/index.js";
+export * from "./enums/index.js";
+export { configureSchemas, defineModel, getSchemaConfig } from "./runtime.js";

package/src/models/Business.js

@@ -0,0 +1,37 @@
+import { Schema } from "mongoose";
+import { defineModel } from "../runtime.js";
+
+const BusinessSchema = new Schema({
+    name: String,
+    logoURL: String,
+    facts: [String],
+    quickQuestions: [{ label: String, value: String }],
+    sector: String,
+    tagline: String,
+    address: String,
+    description: String,
+    MAX_DAYS: { type: Number, default: 45 },
+    contact: {
+        mail: String,
+        phone: String,
+        website: String
+    },
+    createdBy: { type: Schema.Types.ObjectId, ref: "Users" },
+    documents: [{ type: Schema.Types.ObjectId, ref: "document" }],
+    // The credit balance. Only socketio-server writes `balance` — it is derived from the UsageLogs
+    // ledger, so treat it as a cache of the ledger and never increment it directly.
+    credits: {
+        freeTrailClaimed: { type: Boolean, default: false },
+        freeTrailExpiry: { type: Date },
+        currentSubscription: { type: Schema.Types.ObjectId, ref: "Subscriptions" },
+        active: { type: Boolean, default: true },
+        balance: { type: Number, default: 0, min: 0 },
+        carryForward: { type: Number, default: 0, min: 0 },
+        lastUpdated: { type: Date, default: Date.now }
+    }
+}, {
+    timestamps: true
+});
+
+export { BusinessSchema };
+export const Business = defineModel("Businesses", BusinessSchema, "Businesses");

package/src/models/Campaign.js

@@ -0,0 +1,69 @@
+import { Schema } from "mongoose";
+import { defineModel } from "../runtime.js";
+import { CAMPAIGN_STATUS, TASK_REFERENCE_TYPES, TASK_STATUS, TASK_TYPES } from "../enums/index.js";
+
+const TaskSchema = new Schema({
+    business: { type: Schema.Types.ObjectId, ref: 'Businesses', required: true },
+    campaign: { type: Schema.Types.ObjectId, ref: 'Campaign' },
+    lead: { type: Schema.Types.ObjectId, ref: "Lead" },
+    status: { type: String, enum: TASK_STATUS, default: "pending" },
+    timeLine: {
+        startedAt: Date,// start of task
+        failedAt: Date,// failed of task
+        completedAt: Date,// end of task
+    },
+    attempts: { type: Number, default: 1 },
+    type: { type: String, enum: TASK_TYPES, required: true },
+    data: { type: Schema.Types.Mixed, default: null },
+    error: { type: Schema.Types.Mixed, default: null },
+    response: { type: Schema.Types.Mixed, default: null },
+    references: { type: { type: String, enum: TASK_REFERENCE_TYPES }, id: { type: Schema.Types.ObjectId, refPath: "references.type" } },
+}, { timestamps: true });
+
+TaskSchema.methods.updateTimeLine = async function (timeLine, currentStatus) {
+    this.status = currentStatus;
+    this.timeLine[timeLine] = new Date();
+    return this.save();
+};
+
+TaskSchema.methods.updateError = async function (error) {
+    this.error = error;
+    return this.save();
+};
+
+TaskSchema.methods.updateResponse = async function (response) {
+    this.response = response;
+    return this.save();
+};
+
+const CampaignSchema = new Schema({
+    name: String,
+    business: { type: Schema.Types.ObjectId, ref: 'Businesses', required: true },
+    channel: { type: Schema.Types.ObjectId, ref: "Channel", required: true },
+    leads: [{ type: Schema.Types.ObjectId, ref: "Lead" }],
+    config: { type: Schema.Types.Mixed, default: null },
+    status: { type: String, enum: CAMPAIGN_STATUS, default: "pending" },
+    timeLines: {
+        scheduledAt: Date,// scheduled time
+        startedAt: Date,// start of chain
+        completedAt: Date,// end of chain
+        cancelledAt: Date, // breaking the chain 
+        lastTaskStartedAt: Date, // last task started time
+    },
+    cancel_requested: { type: Boolean, default: false }, // if true, the next task will be cancelled
+    createdBy: { type: Schema.Types.ObjectId, ref: 'Users', required: true },
+}, { timestamps: true });
+
+CampaignSchema.methods.updateTimeLine = async function (timeLine, currentStatus) {
+    this.timeLines[timeLine] = new Date();
+    this.status = currentStatus;
+    return this.save();
+};
+
+export { CampaignSchema, TaskSchema };
+export const Campaign = defineModel('Campaign', CampaignSchema, 'Campaign');
+export const Task = defineModel('Task', TaskSchema, 'Tasks');
+
+// `Task.trigger` and `Task.updateReference` stay in socketio-server: they need its RealtimeServer and
+// the Message / CallSession models, which are not in this package yet. socketio attaches them with
+// `Task.prototype.trigger = fn`, which is why the executor is not declared here.

package/src/models/Conversations.js

@@ -0,0 +1,97 @@
+import { Schema } from "mongoose";
+import { defineModel, requireDep } from "../runtime.js";
+import { CONVERSATION_PRIORITY, CONVERSATION_STATUS } from "../enums/index.js";
+import { Trigger } from "./Triggers.js";
+
+const ConversationSchema = new Schema({
+    agent: { type: Schema.Types.ObjectId, ref: 'Agent' },  // the AI agent
+    business: { type: Schema.Types.ObjectId, ref: 'Businesses' },
+    channel: { type: Schema.Types.ObjectId, ref: "Channel" },
+    lead: { type: Schema.Types.ObjectId, ref: "Lead" }, // from sender of the inbound message / call or recipient of the outbound message / call
+    campaign: { type: Schema.Types.ObjectId, ref: "Campaign" }, // participant of the campaign(bulk messaging)
+    // Deterministic provider thread key used to find-or-create on every inbound
+    // event. e.g. WhatsApp: contact wa_id · Telegram: chat.id · Messenger: PSID.
+    externalConversationId: { type: String },
+    // config is the setting that are applied to the conversation,
+    config: {
+        // Human/agent routing — promoted to top level so the agent-inbox index can use it.
+        assignment: {
+            agentReply: { type: Boolean, default: true },
+            handoffReason: String,
+            handoffUrgency: String,
+            // team: { type: Schema.Types.ObjectId, ref: "Team" },
+            assignedAt: Date,
+            assignedTo: String // for support/agent routing in case of support ping to business notifications else give it to agent,
+        },
+        tags: [String],
+        // more settings to be added here
+    },
+    status: { type: String, enum: CONVERSATION_STATUS, default: "open" },
+    priority: { type: String, enum: CONVERSATION_PRIORITY, default: "normal" },
+    metadata: {
+        openai: { "lastResponseId": String, "lastResponseAt": Date },
+        extractedData: Schema.Types.Mixed,
+        userLocation: Schema.Types.Mixed,
+        CreditsUsage: {
+            conversationCredits: { type: Number, default: 0 },
+            analysisCredits: { type: Number, default: 0 },
+            // knowledgeCredits:Number,
+            miscellaneousCredits: { type: Number, default: 0 },
+            totalCredits: { type: Number, default: 0 },
+        }
+    }
+}, {
+    timestamps: true
+});
+
+/**
+ * Moves the conversation to `status`, then announces it.
+ *
+ * The save happens before any publish on purpose. The per-service copies of this method published
+ * the summarisation job and the customer's workflow triggers first, so a status that failed to
+ * validate still dispatched work for a change that never persisted.
+ */
+ConversationSchema.methods.updateStatus = async function (status) {
+    if (!status) throw new Error("@avakado.ai/schemas: Conversation.updateStatus(status) requires a status");
+    const sendKafkaMessage = requireDep("sendKafkaMessage", "Conversation.updateStatus");
+
+    this.status = status;
+    const saved = await this.save();
+
+    // `business` may or may not be populated depending on the caller.
+    const businessId = String(this.business?._id ?? this.business ?? "");
+    const conversationId = this._id.toString();
+
+    await sendKafkaMessage({
+        topic: 'socket-event',
+        message: {
+            key: conversationId,
+            value: JSON.stringify({ event: "conversation.statusUpdated", payload: { conversationId, status }, nameSpace: "CONVERSATION", roomId: businessId }),
+        },
+        acks: -1
+    });
+
+    if (status === "completed") {
+        await sendKafkaMessage({
+            topic: 'agentic-data-summarisation',
+            message: { key: 'conversationStatusUpdated', value: JSON.stringify({ conversationId }) },
+            acks: -1
+        });
+    }
+
+    if (businessId) {
+        const trigger = await Trigger.findOne({ business: businessId, name: "conversationStatusUpdated", type: status });
+        for (const workflow of trigger?.workflows ?? []) {
+            await sendKafkaMessage({
+                topic: 'workflow-execution-trigger',
+                message: { key: workflow.toString(), value: JSON.stringify({ conversationId }) },
+                acks: -1
+            });
+        }
+    }
+
+    return saved;
+};
+
+export { ConversationSchema };
+export const Conversation = defineModel('Conversation', ConversationSchema, "Conversations");

package/src/models/Payments.js

@@ -0,0 +1,38 @@
+import { Schema } from "mongoose";
+import { defineModel } from "../runtime.js";
+import { PAYMENT_STATUS } from "../enums/index.js";
+
+const AmountSchema = new Schema({
+    value: { type: Number, required: true }, // eg: 22000
+    currency: { type: String, default: "INR" }
+}, { _id: false });
+
+// One document per money event. Razorpay is the system of record for the money itself, so we keep
+// its ids here instead of a separate Invoices collection. Credits granted for a payment are posted
+// to the ledger by socketio-server, which reads `notes.credits`.
+const PaymentSchema = new Schema({
+    business: { type: Schema.Types.ObjectId, ref: 'Businesses', required: true },
+    subscription: { type: Schema.Types.ObjectId, ref: 'Subscriptions' },
+    gateway: String,
+    gatewayReference: Schema.Types.Mixed, //{ paymentId: String, orderId: String, invoiceId: String },
+    gatewayPaymentId: { type: String, index: true, sparse: true },
+    gatewayInvoiceId: String, // Razorpay invoice id (inv_xxx) for a subscription cycle; fetch the hosted PDF from Razorpay with it
+    amount: AmountSchema,
+    notes: Schema.Types.Mixed, // { planId, planCode, action, credits }
+    events: {
+        authorized: Date,
+        captured: Date,
+        failed: Date,
+        refunded: Date
+    },
+    status: { type: String, enum: PAYMENT_STATUS, default: 'authorized' },
+    failureReason: String,
+    retryCount: { type: Number, default: 0 },
+    paidAt: Date
+}, {
+    timestamps: true,
+    versionKey: false
+});
+
+export { AmountSchema, PaymentSchema };
+export const Payment = defineModel('Payments', PaymentSchema, "Payments");

package/src/models/Subscriptions.js

@@ -0,0 +1,66 @@
+import { Schema } from "mongoose";
+import { defineModel } from "../runtime.js";
+import { AmountSchema } from "./Payments.js";
+import { CURRENT_SUBSCRIPTION_STATUSES, PENDING_CHANGE_TYPES, SUBSCRIPTION_STATUS } from "../enums/index.js";
+
+const SubscriptionSchema = new Schema({
+    business: { type: Schema.Types.ObjectId, ref: 'Businesses', required: true, index: true },
+    createdBy: { type: Schema.Types.ObjectId, ref: 'Users' },
+    plan: { type: Schema.Types.ObjectId, ref: 'Plans', required: true },
+    planCode: { type: String, required: true, index: true },
+    gateway: { type: String, enum: ['razorpay', 'none'], default: 'razorpay' },
+    gatewaySubscriptionId: { type: String },
+    status: { type: String, enum: SUBSCRIPTION_STATUS, default: 'created', index: true },
+    amount: AmountSchema,
+    creditsPerCycle: { type: Number, default: 0 },
+    spendRatio: { type: Number, enum: [1080, 1666, 1583], default: 1583 },
+    billing: {
+        periodStart: Date,
+        periodEnd: Date,
+        nextChargeAt: Date,
+        paidCount: { type: Number, default: 0 },
+        totalCount: Number
+    },
+    pendingChange: {
+        type: { type: String, enum: PENDING_CHANGE_TYPES },
+        targetPlan: { type: Schema.Types.ObjectId, ref: 'Plans' },
+        targetPlanCode: String,
+        applyAt: Date,
+        chargeAmount: Number,
+        creditDelta: Number,
+        orderId: String
+    },
+    cancelAtPeriodEnd: { type: Boolean, default: false },
+    cancelledAt: Date,
+    cancelReason: String,
+    startedAt: Date,
+    endedAt: Date,
+    shortUrl: String,
+    creditGrant: {
+        lastCycle: { type: Number, default: 0 },
+        lastGrantedAt: Date,
+        lastPaymentId: String
+    },
+    gatewayPayload: Schema.Types.Mixed
+}, {
+    timestamps: true,
+    versionKey: false
+});
+
+SubscriptionSchema.index({ business: 1, createdAt: -1 });
+SubscriptionSchema.index({ business: 1, status: 1, createdAt: -1 });
+SubscriptionSchema.index({ gatewaySubscriptionId: 1 }, { unique: true, sparse: true });
+// Mongo cannot redefine an index under an existing name with different options — it keeps the old
+// one and the createIndex call fails. Changing this filter is a MAJOR bump, and each environment
+// needs `dropIndex('one_current_subscription_per_business')` before the new spec can be built.
+SubscriptionSchema.index(
+    { business: 1 },
+    {
+        unique: true,
+        name: 'one_current_subscription_per_business',
+        partialFilterExpression: { status: { $in: CURRENT_SUBSCRIPTION_STATUSES } }
+    }
+);
+
+export { SubscriptionSchema };
+export const Subscription = defineModel('Subscriptions', SubscriptionSchema, "Subscriptions");

package/src/models/Triggers.js

@@ -0,0 +1,17 @@
+import { Schema } from "mongoose";
+import { defineModel } from "../runtime.js";
+
+const TriggerSchema = new Schema({
+    business: { type: Schema.Types.ObjectId, ref: 'Businesses' },
+    name: String, // conversationStatusUpdated, leadStatusUpdated, 
+    description: String,
+    type: String, // [open, pending, snoozed, completed, closed, archived, spam] || [new, contacted, qualified, converted, lost]
+    workflows: [{ type: Schema.Types.ObjectId, ref: "Workflow" }],
+}, {
+    timestamps: true,
+});
+
+export { TriggerSchema };
+// No explicit collection name, matching the services: mongoose pluralises this to `triggers`.
+export const Trigger = defineModel('Trigger', TriggerSchema);
+export default Trigger;

package/src/models/UsageLogs.js

@@ -0,0 +1,32 @@
+import { Schema } from "mongoose";
+import { defineModel } from "../runtime.js";
+import { LEDGER_DIRECTIONS, LEDGER_SOURCE_TYPES, LEDGER_STATUSES } from "../enums/index.js";
+
+// The credit ledger, and the only source of truth for credit movement. socketio-server is its only
+// writer; every other service asks for a ledger entry over Kafka. `Business.credits.balance` is a
+// cache of the running total here.
+const UsageLogSchema = new Schema({
+    business: { type: Schema.Types.ObjectId, ref: "Businesses", required: true, index: true },
+    direction: { type: String, enum: LEDGER_DIRECTIONS, required: true },
+    credits: { type: Number, required: true, min: 0 },
+    status: { type: String, enum: LEDGER_STATUSES, default: "posted" },
+    payment: { type: Schema.Types.ObjectId, ref: "Payments" },
+    source: {
+        type: { type: String, enum: LEDGER_SOURCE_TYPES },
+        id: { type: Schema.Types.ObjectId, refPath: "source.type" },
+    },
+    idempotencyKey: { type: String },
+    meta: Schema.Types.Mixed,
+    note: String,
+    createdBy: { type: Schema.Types.ObjectId, ref: "Users" }
+}, {
+    timestamps: true,
+    versionKey: false
+});
+
+UsageLogSchema.index({ business: 1, direction: 1, createdAt: -1 });
+// The idempotency guarantee for every credit movement. Replaying a Kafka message must not double-post.
+UsageLogSchema.index({ idempotencyKey: 1 }, { unique: true, sparse: true });
+
+export { UsageLogSchema };
+export const UsageLog = defineModel("UsageLog", UsageLogSchema, "UsageLogs");

package/src/models/index.js

@@ -0,0 +1,7 @@
+export { Business, BusinessSchema } from "./Business.js";
+export { AmountSchema, Payment, PaymentSchema } from "./Payments.js";
+export { Subscription, SubscriptionSchema } from "./Subscriptions.js";
+export { UsageLog, UsageLogSchema } from "./UsageLogs.js";
+export { Conversation, ConversationSchema } from "./Conversations.js";
+export { Campaign, CampaignSchema, Task, TaskSchema } from "./Campaign.js";
+export { Trigger, TriggerSchema } from "./Triggers.js";

package/src/runtime.js

@@ -0,0 +1,45 @@
+import mongoose from "mongoose";
+
+/**
+ * Registers a model once per mongoose instance.
+ *
+ * Importing the same model file twice — two copies of this package on disk, a test that reloads a
+ * module, a service that imports both `@avakado.ai/schemas` and `@avakado.ai/schemas/models/Business.js` —
+ * would otherwise throw `OverwriteModelError`. Reusing the already-registered model also guarantees
+ * one model per name, which is what `populate` resolves refs against.
+ */
+export function defineModel(name, schema, collection) {
+    return mongoose.models[name] ?? mongoose.model(name, schema, collection);
+}
+
+/**
+ * Host-supplied capabilities. The package never imports a service's utils, so anything a shared
+ * model needs from its host arrives here at startup instead.
+ */
+const deps = {
+    /** ({ topic, message, acks }) => Promise<void> — the service's Kafka producer. */
+    sendKafkaMessage: null,
+};
+
+export function configureSchemas(next = {}) {
+    for (const [key, value] of Object.entries(next)) {
+        if (!(key in deps)) throw new Error(`@avakado.ai/schemas: unknown option "${key}" passed to configureSchemas`);
+        deps[key] = value;
+    }
+    return { ...deps };
+}
+
+export function getSchemaConfig() {
+    return { ...deps };
+}
+
+export function requireDep(name, neededBy) {
+    const value = deps[name];
+    if (typeof value !== "function") {
+        throw new Error(
+            `@avakado.ai/schemas: "${name}" is not configured but ${neededBy} needs it. ` +
+            `Call configureSchemas({ ${name} }) once during service startup.`
+        );
+    }
+    return value;
+}