@pegma/support-desk-contracts 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pegma contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,9 @@
+# @pegma/support-desk-contracts
+
+Provider-neutral ticket, requester, message, and event contracts shared by
+Support Desk packages and host applications.
+
+`Ticket` carries optional host-configured `category` and dual timestamps:
+staff-facing `updatedAt` and customer-visible `customerUpdatedAt`. Category is
+an opaque allowlisted label and never establishes identity, permission,
+priority, or assignment.

package/dist/index.d.ts

@@ -0,0 +1,120 @@
+import type { IsoTimestamp, PrincipalId } from "@pegma/spine";
+/**
+ * Identity and time are ecosystem-wide, not Support Desk's to define.
+ *
+ * A principal resolved by `@pegma/authorization-core` has to be the same value
+ * Support Desk stores on a ticket, authorizes a reply against, and writes into
+ * an audit event. Declaring the type locally would make that agreement a
+ * coincidence rather than something the compiler checks, so both come from
+ * `@pegma/spine` and are re-exported here for convenience.
+ */
+export type { IsoTimestamp, PrincipalId };
+export type TicketId = string;
+export type MessageId = string;
+export type TicketChannel = "web" | "email" | "api";
+export type TicketPriority = "low" | "normal" | "high" | "urgent";
+export type TicketStatus = "open" | "waiting_on_support" | "waiting_on_customer" | "resolved" | "closed";
+/**
+ * Describes how a requester was associated with an account.
+ *
+ * `matched_email` is useful for routing and context, but is explicitly not an
+ * authenticated identity.
+ */
+export type RequesterAssociation = "authenticated" | "matched_email" | "unverified";
+export interface TicketRequester {
+    readonly association: RequesterAssociation;
+    readonly principalId?: PrincipalId;
+    readonly email?: string;
+    readonly displayName?: string;
+}
+/** Current ticket state stored with optimistic-concurrency revision. */
+export interface Ticket {
+    readonly id: TicketId;
+    readonly number: number;
+    readonly revision: number;
+    readonly subject: string;
+    /**
+     * Optional host-configured opaque label (for example `bug` or `feedback`).
+     * Never establishes identity, permission, priority, or assignment.
+     */
+    readonly category?: string;
+    readonly channel: TicketChannel;
+    readonly status: TicketStatus;
+    readonly priority: TicketPriority;
+    readonly requester: TicketRequester;
+    readonly assignedTo?: PrincipalId;
+    readonly createdAt: IsoTimestamp;
+    /** Staff-facing update time; advances on every accepted ticket change. */
+    readonly updatedAt: IsoTimestamp;
+    /**
+     * Customer-visible update time. Advances for customer-visible messages and
+     * lifecycle changes; notes, assignment, and priority leave it unchanged.
+     */
+    readonly customerUpdatedAt: IsoTimestamp;
+    readonly resolvedAt?: IsoTimestamp;
+    readonly closedAt?: IsoTimestamp;
+}
+export type MessageAuthorKind = "customer" | "staff" | "system";
+export type MessageVisibility = "customer" | "internal";
+export type MessageFormat = "plain_text" | "markdown";
+/**
+ * One canonical message in a ticket conversation.
+ *
+ * Mail adapters should convert and sanitize provider content before producing
+ * this contract. Raw MIME payloads and unsafe HTML do not belong here.
+ */
+export interface TicketMessage {
+    readonly id: MessageId;
+    readonly ticketId: TicketId;
+    readonly authorKind: MessageAuthorKind;
+    readonly authorPrincipalId?: PrincipalId;
+    readonly channel: TicketChannel;
+    readonly visibility: MessageVisibility;
+    readonly format: MessageFormat;
+    readonly body: string;
+    readonly createdAt: IsoTimestamp;
+    readonly externalMessageId?: string;
+    readonly inReplyToExternalMessageId?: string;
+}
+export interface CreateTicketInput {
+    readonly id: TicketId;
+    readonly number: number;
+    readonly subject: string;
+    readonly channel: TicketChannel;
+    readonly priority?: TicketPriority;
+    /** Optional host-validated opaque category; preserved for the ticket life. */
+    readonly category?: string;
+    readonly requester: TicketRequester;
+    readonly createdAt: IsoTimestamp;
+}
+interface TicketEventBase {
+    readonly occurredAt: IsoTimestamp;
+}
+export type TicketEvent = (TicketEventBase & {
+    readonly type: "customer_replied";
+    readonly actorId?: PrincipalId;
+}) | (TicketEventBase & {
+    readonly type: "support_replied";
+    readonly actorId: PrincipalId;
+}) | (TicketEventBase & {
+    readonly type: "note_added";
+    readonly actorId: PrincipalId;
+}) | (TicketEventBase & {
+    readonly type: "resolved";
+    readonly actorId: PrincipalId;
+}) | (TicketEventBase & {
+    readonly type: "closed";
+    readonly actorId: PrincipalId;
+}) | (TicketEventBase & {
+    readonly type: "reopened";
+    readonly actorId: PrincipalId;
+}) | (TicketEventBase & {
+    readonly type: "assigned";
+    readonly actorId: PrincipalId;
+    readonly assigneeId: PrincipalId | null;
+}) | (TicketEventBase & {
+    readonly type: "priority_changed";
+    readonly actorId: PrincipalId;
+    readonly priority: TicketPriority;
+});
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@pegma/support-desk-contracts",
+  "version": "0.1.0",
+  "description": "Provider-neutral ticket and message contracts for Support Desk.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map",
+    "dist/**/*.js",
+    "dist/**/*.js.map"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pegma-dev/support-desk.git",
+    "directory": "packages/contracts"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@pegma/spine": "0.1.1"
+  }
+}