@contractspec/example.service-business-os 1.57.0 → 1.59.0

package/dist/browser/client/client.operations.js

@@ -0,0 +1,72 @@
+// src/client/client.schema.ts
+import { defineSchemaModel, ScalarTypeEnum } from "@contractspec/lib.schema";
+var ClientModel = defineSchemaModel({
+  name: "Client",
+  description: "Client profile",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    contactEmail: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    phone: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    orgId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    ownerId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var CreateClientInputModel = defineSchemaModel({
+  name: "CreateClientInput",
+  description: "Input for creating a client",
+  fields: {
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    contactEmail: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    phone: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    orgId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    ownerId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    metadata: { type: ScalarTypeEnum.JSON(), isOptional: true }
+  }
+});
+
+// src/client/client.operations.ts
+import { defineCommand } from "@contractspec/lib.contracts";
+var OWNERS = ["@examples.service-business-os"];
+var CreateClientContract = defineCommand({
+  meta: {
+    key: "service.client.create",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["service-business-os", "client", "create"],
+    description: "Create a new client.",
+    goal: "Onboard clients.",
+    context: "CRM."
+  },
+  io: {
+    input: CreateClientInputModel,
+    output: ClientModel
+  },
+  policy: { auth: "user" },
+  acceptance: {
+    scenarios: [
+      {
+        key: "create-client-happy-path",
+        given: ["User is authenticated"],
+        when: ["User creates a new client"],
+        then: ["Client is created"]
+      }
+    ],
+    examples: [
+      {
+        key: "create-basic",
+        input: {
+          name: "Acme Corp",
+          email: "contact@acme.com",
+          phone: "555-0123"
+        },
+        output: { id: "client-123", name: "Acme Corp" }
+      }
+    ]
+  }
+});
+export {
+  CreateClientContract
+};

package/dist/browser/client/client.schema.js

@@ -0,0 +1,31 @@
+// src/client/client.schema.ts
+import { defineSchemaModel, ScalarTypeEnum } from "@contractspec/lib.schema";
+var ClientModel = defineSchemaModel({
+  name: "Client",
+  description: "Client profile",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    contactEmail: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    phone: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    orgId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    ownerId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var CreateClientInputModel = defineSchemaModel({
+  name: "CreateClientInput",
+  description: "Input for creating a client",
+  fields: {
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    contactEmail: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    phone: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    orgId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    ownerId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    metadata: { type: ScalarTypeEnum.JSON(), isOptional: true }
+  }
+});
+export {
+  CreateClientInputModel,
+  ClientModel
+};

package/dist/browser/client/index.js

@@ -0,0 +1,74 @@
+// src/client/client.schema.ts
+import { defineSchemaModel, ScalarTypeEnum } from "@contractspec/lib.schema";
+var ClientModel = defineSchemaModel({
+  name: "Client",
+  description: "Client profile",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    contactEmail: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    phone: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    orgId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    ownerId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var CreateClientInputModel = defineSchemaModel({
+  name: "CreateClientInput",
+  description: "Input for creating a client",
+  fields: {
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    contactEmail: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    phone: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    orgId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    ownerId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    metadata: { type: ScalarTypeEnum.JSON(), isOptional: true }
+  }
+});
+
+// src/client/client.operations.ts
+import { defineCommand } from "@contractspec/lib.contracts";
+var OWNERS = ["@examples.service-business-os"];
+var CreateClientContract = defineCommand({
+  meta: {
+    key: "service.client.create",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["service-business-os", "client", "create"],
+    description: "Create a new client.",
+    goal: "Onboard clients.",
+    context: "CRM."
+  },
+  io: {
+    input: CreateClientInputModel,
+    output: ClientModel
+  },
+  policy: { auth: "user" },
+  acceptance: {
+    scenarios: [
+      {
+        key: "create-client-happy-path",
+        given: ["User is authenticated"],
+        when: ["User creates a new client"],
+        then: ["Client is created"]
+      }
+    ],
+    examples: [
+      {
+        key: "create-basic",
+        input: {
+          name: "Acme Corp",
+          email: "contact@acme.com",
+          phone: "555-0123"
+        },
+        output: { id: "client-123", name: "Acme Corp" }
+      }
+    ]
+  }
+});
+export {
+  CreateClientInputModel,
+  CreateClientContract,
+  ClientModel
+};

package/dist/browser/docs/index.js

@@ -0,0 +1,96 @@
+// src/docs/service-business-os.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+var serviceBusinessDocBlocks = [
+  {
+    id: "docs.examples.service-business-os",
+    title: "Service Business OS",
+    summary: "Field/service business flow from client intake to quote, job scheduling, invoicing, and payments with notifications and audit trail.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/examples/service-business-os",
+    tags: ["services", "quotes", "jobs", "invoices", "payments"],
+    body: `## Flows
+
+1) **Client intake** → create client, capture contact + owner.
+2) **Quote** → draft, send, accept/reject (events + notifications).
+3) **Job** → schedule, assign technician, complete with notes and attachments.
+4) **Invoice** → issue after completion, track status.
+5) **Payment** → record payment and emit analytics/audit.
+
+## Modules reused
+- Identity/RBAC for org + roles
+- Files for attachments (proposals, receipts)
+- Notifications for quote sent/accepted, job reminders, overdue invoices
+- Jobs for reminder/schedule tasks
+- Audit trail for all lifecycle changes
+
+## Presentations
+- Dashboard, client list, quote list/detail, job board, invoice list, payment list (React + Markdown targets).
+`
+  },
+  {
+    id: "docs.examples.service-business-os.goal",
+    title: "Service Business OS — Goal",
+    summary: "Why this field-service OS exists and outcomes it targets.",
+    kind: "goal",
+    visibility: "public",
+    route: "/docs/examples/service-business-os/goal",
+    tags: ["services", "goal"],
+    body: `## Why it matters
+- Provides a regenerable, end-to-end service lifecycle (client → quote → job → invoice → payment).
+- Keeps pricing, scheduling, invoicing, and payments consistent across surfaces.
+
+## Business/Product goal
+- Deliver auditable quotes/jobs/invoices with notifications and reminders.
+- Support attachments and PII-safe flows; stage new payment rules via feature flags.
+
+## Success criteria
+- Spec changes regenerate UI/API/events cleanly across lifecycle steps.
+- Audit/Notifications/Jobs remain wired for every mutation.`
+  },
+  {
+    id: "docs.examples.service-business-os.usage",
+    title: "Service Business OS — Usage",
+    summary: "How to operate, extend, and regenerate the service OS safely.",
+    kind: "usage",
+    visibility: "public",
+    route: "/docs/examples/service-business-os/usage",
+    tags: ["services", "usage"],
+    body: `## Setup
+1) Seed (if provided) or create client → quote → job → invoice → payment via UI.
+2) Configure Files for attachments and Notifications for quote/job/invoice events.
+
+## Extend & regenerate
+1) Adjust schemas: quote line items, job statuses, invoice terms, payment methods.
+2) Regenerate to sync UI/API/events; mark PII paths in policy.
+3) Use Feature Flags to trial new payment rules or reminder cadences.
+
+## Guardrails
+- Emit events for quote accepted/rejected, job scheduled/completed, invoice overdue, payment recorded.
+- Keep pricing/tax rules explicit in spec; avoid implicit handler math.
+- Use Audit Trail for lifecycle mutations; schedule reminders via Jobs.`
+  },
+  {
+    id: "docs.examples.service-business-os.constraints",
+    title: "Service Business OS — Constraints & Safety",
+    summary: "Internal guardrails for quotes/jobs/invoices/payments and regeneration safety.",
+    kind: "reference",
+    visibility: "internal",
+    route: "/docs/examples/service-business-os/constraints",
+    tags: ["services", "constraints", "internal"],
+    body: `## Constraints
+- Commission/tax/payment rules must be explicit in spec; no hidden handler math.
+- Events to emit: quote.sent/accepted/rejected, job.scheduled/completed, invoice.issued/overdue, payment.recorded.
+- Regeneration must not alter payment semantics without reviewed spec changes.
+
+## PII & Attachments
+- Mark PII paths (client contact, address); redact in markdown/JSON.
+- Files (quotes, receipts) should use presigned URLs with scoped access.
+
+## Verification
+- Add fixtures for quote/job/invoice state transitions.
+- Ensure Notifications/Audit/Jobs wiring persists after regeneration.
+- Use Feature Flags to trial new payment rules/reminder cadences; default safe/off.`
+  }
+];
+registerDocBlocks(serviceBusinessDocBlocks);

package/dist/browser/docs/service-business-os.docblock.js

@@ -0,0 +1,96 @@
+// src/docs/service-business-os.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+var serviceBusinessDocBlocks = [
+  {
+    id: "docs.examples.service-business-os",
+    title: "Service Business OS",
+    summary: "Field/service business flow from client intake to quote, job scheduling, invoicing, and payments with notifications and audit trail.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/examples/service-business-os",
+    tags: ["services", "quotes", "jobs", "invoices", "payments"],
+    body: `## Flows
+
+1) **Client intake** → create client, capture contact + owner.
+2) **Quote** → draft, send, accept/reject (events + notifications).
+3) **Job** → schedule, assign technician, complete with notes and attachments.
+4) **Invoice** → issue after completion, track status.
+5) **Payment** → record payment and emit analytics/audit.
+
+## Modules reused
+- Identity/RBAC for org + roles
+- Files for attachments (proposals, receipts)
+- Notifications for quote sent/accepted, job reminders, overdue invoices
+- Jobs for reminder/schedule tasks
+- Audit trail for all lifecycle changes
+
+## Presentations
+- Dashboard, client list, quote list/detail, job board, invoice list, payment list (React + Markdown targets).
+`
+  },
+  {
+    id: "docs.examples.service-business-os.goal",
+    title: "Service Business OS — Goal",
+    summary: "Why this field-service OS exists and outcomes it targets.",
+    kind: "goal",
+    visibility: "public",
+    route: "/docs/examples/service-business-os/goal",
+    tags: ["services", "goal"],
+    body: `## Why it matters
+- Provides a regenerable, end-to-end service lifecycle (client → quote → job → invoice → payment).
+- Keeps pricing, scheduling, invoicing, and payments consistent across surfaces.
+
+## Business/Product goal
+- Deliver auditable quotes/jobs/invoices with notifications and reminders.
+- Support attachments and PII-safe flows; stage new payment rules via feature flags.
+
+## Success criteria
+- Spec changes regenerate UI/API/events cleanly across lifecycle steps.
+- Audit/Notifications/Jobs remain wired for every mutation.`
+  },
+  {
+    id: "docs.examples.service-business-os.usage",
+    title: "Service Business OS — Usage",
+    summary: "How to operate, extend, and regenerate the service OS safely.",
+    kind: "usage",
+    visibility: "public",
+    route: "/docs/examples/service-business-os/usage",
+    tags: ["services", "usage"],
+    body: `## Setup
+1) Seed (if provided) or create client → quote → job → invoice → payment via UI.
+2) Configure Files for attachments and Notifications for quote/job/invoice events.
+
+## Extend & regenerate
+1) Adjust schemas: quote line items, job statuses, invoice terms, payment methods.
+2) Regenerate to sync UI/API/events; mark PII paths in policy.
+3) Use Feature Flags to trial new payment rules or reminder cadences.
+
+## Guardrails
+- Emit events for quote accepted/rejected, job scheduled/completed, invoice overdue, payment recorded.
+- Keep pricing/tax rules explicit in spec; avoid implicit handler math.
+- Use Audit Trail for lifecycle mutations; schedule reminders via Jobs.`
+  },
+  {
+    id: "docs.examples.service-business-os.constraints",
+    title: "Service Business OS — Constraints & Safety",
+    summary: "Internal guardrails for quotes/jobs/invoices/payments and regeneration safety.",
+    kind: "reference",
+    visibility: "internal",
+    route: "/docs/examples/service-business-os/constraints",
+    tags: ["services", "constraints", "internal"],
+    body: `## Constraints
+- Commission/tax/payment rules must be explicit in spec; no hidden handler math.
+- Events to emit: quote.sent/accepted/rejected, job.scheduled/completed, invoice.issued/overdue, payment.recorded.
+- Regeneration must not alter payment semantics without reviewed spec changes.
+
+## PII & Attachments
+- Mark PII paths (client contact, address); redact in markdown/JSON.
+- Files (quotes, receipts) should use presigned URLs with scoped access.
+
+## Verification
+- Add fixtures for quote/job/invoice state transitions.
+- Ensure Notifications/Audit/Jobs wiring persists after regeneration.
+- Use Feature Flags to trial new payment rules/reminder cadences; default safe/off.`
+  }
+];
+registerDocBlocks(serviceBusinessDocBlocks);

package/dist/browser/entities/index.js

@@ -0,0 +1,246 @@
+// src/entities/index.ts
+import {
+  defineEntity,
+  defineEntityEnum,
+  field,
+  index
+} from "@contractspec/lib.schema";
+var schema = "lssm_service_os";
+var QuoteStatusEnum = defineEntityEnum({
+  name: "QuoteStatus",
+  schema,
+  values: ["DRAFT", "SENT", "ACCEPTED", "REJECTED", "EXPIRED"],
+  description: "Lifecycle for quotes/proposals."
+});
+var JobStatusEnum = defineEntityEnum({
+  name: "JobStatus",
+  schema,
+  values: ["SCHEDULED", "IN_PROGRESS", "COMPLETED", "CANCELLED"],
+  description: "Lifecycle for service jobs/interventions."
+});
+var InvoiceStatusEnum = defineEntityEnum({
+  name: "InvoiceStatus",
+  schema,
+  values: ["DRAFT", "SENT", "PAID", "OVERDUE", "CANCELLED"],
+  description: "Lifecycle for invoices."
+});
+var PaymentMethodEnum = defineEntityEnum({
+  name: "PaymentMethod",
+  schema,
+  values: ["CARD", "BANK_TRANSFER", "CASH", "CHECK"],
+  description: "Payment method used."
+});
+var ClientEntity = defineEntity({
+  name: "Client",
+  description: "Customer organization or individual.",
+  schema,
+  map: "client",
+  fields: {
+    id: field.id({ description: "Unique client identifier" }),
+    name: field.string({ description: "Client display name" }),
+    contactEmail: field.string({
+      description: "Primary contact email",
+      isOptional: true
+    }),
+    phone: field.string({ description: "Primary phone", isOptional: true }),
+    address: field.json({ description: "Mailing address", isOptional: true }),
+    industry: field.string({
+      description: "Industry/vertical",
+      isOptional: true
+    }),
+    orgId: field.string({ description: "Owning organization" }),
+    ownerId: field.string({ description: "Account owner" }),
+    metadata: field.json({
+      description: "Additional metadata",
+      isOptional: true
+    }),
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt(),
+    quotes: field.hasMany("Quote"),
+    jobs: field.hasMany("Job")
+  },
+  indexes: [index.on(["orgId"]), index.on(["ownerId"]), index.on(["name"])]
+});
+var QuoteEntity = defineEntity({
+  name: "Quote",
+  description: "Proposal/quote for a job.",
+  schema,
+  map: "quote",
+  fields: {
+    id: field.id({ description: "Unique quote identifier" }),
+    clientId: field.foreignKey({ description: "Client receiving quote" }),
+    title: field.string({ description: "Quote title" }),
+    description: field.string({
+      description: "Work summary",
+      isOptional: true
+    }),
+    amount: field.float({ description: "Total quoted amount" }),
+    currency: field.string({ description: "Currency code", default: '"USD"' }),
+    status: field.enum("QuoteStatus", {
+      description: "Quote status",
+      default: "DRAFT"
+    }),
+    validUntil: field.dateTime({
+      description: "Expiration date",
+      isOptional: true
+    }),
+    terms: field.string({
+      description: "Payment/engagement terms",
+      isOptional: true
+    }),
+    orgId: field.string({ description: "Owning organization" }),
+    ownerId: field.string({ description: "Account owner" }),
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt(),
+    client: field.belongsTo("Client", ["clientId"], ["id"], {
+      onDelete: "Cascade"
+    }),
+    jobs: field.hasMany("Job")
+  },
+  enums: [QuoteStatusEnum],
+  indexes: [
+    index.on(["orgId", "status"]),
+    index.on(["clientId"]),
+    index.on(["validUntil"])
+  ]
+});
+var JobEntity = defineEntity({
+  name: "Job",
+  description: "Service job/intervention derived from an accepted quote.",
+  schema,
+  map: "job",
+  fields: {
+    id: field.id({ description: "Unique job identifier" }),
+    quoteId: field.foreignKey({ description: "Source quote" }),
+    clientId: field.foreignKey({ description: "Client receiving service" }),
+    title: field.string({ description: "Job title" }),
+    status: field.enum("JobStatus", {
+      description: "Job status",
+      default: "SCHEDULED"
+    }),
+    scheduledAt: field.dateTime({
+      description: "Scheduled start date/time",
+      isOptional: true
+    }),
+    completedAt: field.dateTime({
+      description: "Completion timestamp",
+      isOptional: true
+    }),
+    assignedTo: field.string({
+      description: "Assignee/technician user ID",
+      isOptional: true
+    }),
+    location: field.json({ description: "Location details", isOptional: true }),
+    notes: field.string({ description: "Internal notes", isOptional: true }),
+    orgId: field.string({ description: "Owning organization" }),
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt(),
+    quote: field.belongsTo("Quote", ["quoteId"], ["id"], {
+      onDelete: "SetNull"
+    }),
+    client: field.belongsTo("Client", ["clientId"], ["id"], {
+      onDelete: "Cascade"
+    }),
+    invoices: field.hasMany("Invoice")
+  },
+  enums: [JobStatusEnum],
+  indexes: [
+    index.on(["orgId", "status"]),
+    index.on(["clientId"]),
+    index.on(["assignedTo", "status"]),
+    index.on(["scheduledAt"])
+  ]
+});
+var InvoiceEntity = defineEntity({
+  name: "Invoice",
+  description: "Invoice issued for a completed job.",
+  schema,
+  map: "invoice",
+  fields: {
+    id: field.id({ description: "Unique invoice identifier" }),
+    jobId: field.foreignKey({ description: "Related job" }),
+    invoiceNumber: field.string({
+      description: "Invoice number",
+      isUnique: true
+    }),
+    amount: field.decimal({ description: "Invoice amount" }),
+    currency: field.string({ description: "Currency code", default: '"USD"' }),
+    status: field.enum("InvoiceStatus", {
+      description: "Invoice status",
+      default: "DRAFT"
+    }),
+    dueDate: field.dateTime({ description: "Due date", isOptional: true }),
+    issuedAt: field.dateTime({
+      description: "Issued timestamp",
+      isOptional: true
+    }),
+    paidAt: field.dateTime({ description: "Paid timestamp", isOptional: true }),
+    orgId: field.string({ description: "Owning organization" }),
+    notes: field.string({ description: "Invoice notes", isOptional: true }),
+    metadata: field.json({ description: "Metadata", isOptional: true }),
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt(),
+    job: field.belongsTo("Job", ["jobId"], ["id"], { onDelete: "Cascade" }),
+    payments: field.hasMany("Payment")
+  },
+  enums: [InvoiceStatusEnum],
+  indexes: [
+    index.on(["invoiceNumber"]),
+    index.on(["orgId", "status"]),
+    index.on(["dueDate"])
+  ]
+});
+var PaymentEntity = defineEntity({
+  name: "Payment",
+  description: "Payment received for an invoice.",
+  schema,
+  map: "payment",
+  fields: {
+    id: field.id({ description: "Unique payment identifier" }),
+    invoiceId: field.foreignKey({ description: "Invoice being paid" }),
+    amount: field.decimal({ description: "Payment amount" }),
+    currency: field.string({ description: "Currency code", default: '"USD"' }),
+    method: field.enum("PaymentMethod", { description: "Payment method" }),
+    reference: field.string({
+      description: "Payment reference/transaction ID",
+      isOptional: true
+    }),
+    receivedAt: field.dateTime({ description: "When payment was received" }),
+    orgId: field.string({ description: "Owning organization" }),
+    createdAt: field.createdAt(),
+    invoice: field.belongsTo("Invoice", ["invoiceId"], ["id"], {
+      onDelete: "Cascade"
+    })
+  },
+  enums: [PaymentMethodEnum],
+  indexes: [
+    index.on(["invoiceId"]),
+    index.on(["orgId"]),
+    index.on(["receivedAt"])
+  ]
+});
+var serviceBusinessEntities = [
+  ClientEntity,
+  QuoteEntity,
+  JobEntity,
+  InvoiceEntity,
+  PaymentEntity
+];
+var serviceBusinessSchemaContribution = {
+  moduleId: "@contractspec/example.service-business-os",
+  entities: serviceBusinessEntities,
+  enums: [QuoteStatusEnum, JobStatusEnum, InvoiceStatusEnum, PaymentMethodEnum]
+};
+export {
+  serviceBusinessSchemaContribution,
+  serviceBusinessEntities,
+  QuoteStatusEnum,
+  QuoteEntity,
+  PaymentMethodEnum,
+  PaymentEntity,
+  JobStatusEnum,
+  JobEntity,
+  InvoiceStatusEnum,
+  InvoiceEntity,
+  ClientEntity
+};