@opencxh/domain 1.275.0 → 1.277.0

package/dist/entities/transaction/convert.d.ts

@@ -13,8 +13,24 @@ export declare function isFrozen(transaction: Pick<Transaction, "issuedAt">): bo
  * Everything else is a `BadRequestError`. Whoever wants to change a sent quote gets v2.
  */
 export declare const FROZEN_WRITABLE_FIELDS: readonly (keyof Transaction)[];
+/**
+ * What a save may set on a draft. `status` is not here: it moves through `issue` and the status
+ * route, which check the transition and announce it.
+ */
+export declare const DRAFT_FIELDS: readonly ["companyId", "contactId", "dealItemId", "title", "reference", "currency", "taxOverrideKey", "introText", "termsText", "expiresAt", "deliveredAt", "periodFrom", "periodTo", "paymentTerm", "lines"];
+/**
+ * The draft fields a save may empty, named in `clear`. A list and not `null` in the body:
+ * `invoke` strips `null`, so "empty this" never reaches the server any other way.
+ */
+export declare const CLEARABLE_FIELDS: readonly ["contactId", "dealItemId", "title", "reference", "taxOverrideKey", "introText", "termsText", "expiresAt", "deliveredAt", "periodFrom", "periodTo"];
+export type ClearableField = (typeof CLEARABLE_FIELDS)[number];
 /** The fields a draft carries over; the server owns id, organisation and author. */
 export type TransactionDraft = Omit<Transaction, "id" | "organizationId" | "createdBy" | "createdAt" | "updatedAt">;
+/**
+ * Whether `source` may become a `kindKey`: offered, a step the source's kind allows, and for a
+ * correcting kind (a credit note) only from the issued document it corrects.
+ */
+export declare function canConvert(source: Pick<Transaction, "kindKey" | "issuedAt">, kindKey: string): boolean;
 /**
  * The conversion: quote -> order -> invoice -> credit note, as one function.
  *

package/dist/entities/transaction/document.d.ts

@@ -24,6 +24,8 @@ export interface TransactionContextSources {
     organizationName?: string;
     /** Who the recipient reads; drives which template row is picked. */
     locale?: string;
+    /** The number of the document a credit note corrects. */
+    creditedNumber?: string;
 }
 /**
  * The tokens: `{customer.name}`, `{quote.number}`, `{totals.gross}`.

package/dist/entities/transaction/keys.d.ts

@@ -12,6 +12,21 @@ export declare const PRODUCT_SCOPE_KIND = "product";
 /** `invoice:412`. The kind of a transaction *is* its kind key — no mapping table. */
 export declare function transactionScopeKey(kindKey: string, id: string): string;
 export declare function productScopeKey(id: string): string;
+/**
+ * The shell path of a document, under the administration it belongs to.
+ *
+ * `fallbackEntityId` is for a row that predates administrations (`""` = the default one); without
+ * either there is no screen to point at, and no link beats a dead one.
+ */
+export declare function transactionHref(row: {
+    id: string;
+    kindKey: string;
+    businessEntityId?: string;
+}, fallbackEntityId?: string): string | undefined;
+export declare function productHref(row: {
+    id: string;
+    businessEntityId?: string;
+}, fallbackEntityId?: string): string | undefined;
 /** Is this scopeKey one of ours, and which id does it point at? */
 export declare function transactionIdFromScope(scopeKey: string): string | undefined;
 /**

package/dist/entities/transaction/kinds.d.ts

@@ -13,8 +13,12 @@ import { TransactionStatus } from './types';
  */
 export interface TransactionKind {
     key: string;
-    /** i18n key, not text. */
+    /** i18n key, not text. For a screen that has `t()`. */
     label: string;
+    /** Dutch, for what the server writes itself: an approval title, a related row, a card. */
+    name: string;
+    /** What the seeded template row is called, when the paper has another name than the kind. */
+    paperName?: string;
     /** Gets a number from a series when issued. */
     numbered: boolean;
     /** Invert amounts: a credit note is an invoice with a minus sign. */
@@ -35,6 +39,19 @@ export interface TransactionKind {
      * invoice or a credit note.
      */
     issuedStatus: TransactionStatus;
+    /**
+     * The answers a person may give after issuing, per status. `draft -> issuedStatus` is not in
+     * here: that move is `issue`, with its gate and its number. Walking back one step is allowed —
+     * a mis-click on "accepted" must not need a new version.
+     */
+    transitions: Partial<Record<TransactionStatus, readonly TransactionStatus[]>>;
+    /** What this kind may become through `convert`. A revision of the same kind is `version`. */
+    convertsTo: readonly string[];
+    /**
+     * The kind this one corrects. Made only from an issued document of that kind, which the paper
+     * names: a credit note without its invoice number is not a credit note.
+     */
+    credits?: string;
 }
 export declare const TRANSACTION_KINDS: readonly TransactionKind[];
 /**
@@ -45,9 +62,8 @@ export declare const TRANSACTION_KINDS: readonly TransactionKind[];
  * A product decision, like the kinds themselves — §12.4: *"transactiesoorten zijn van ons, niet
  * van de organisatie"*.
  *
- * `credit_note` is deliberately absent. Crediting an invoice is its own small feature — which
- * lines, partial credits, the reference back — and a kind you can create but not fill correctly is
- * worse than one you cannot create at all.
+ * A credit note credits one issued invoice, whole or in part: the lines come over negated and a
+ * person lowers or removes what is not credited.
  */
 export declare const ENABLED_TRANSACTION_KINDS: readonly string[];
 /** The kinds a reader can browse, one per route segment. A credit note files with the invoices. */
@@ -60,3 +76,8 @@ export declare function listedTransactionKinds(): TransactionKind[];
  * amounts on a guess is worse than showing a document with a strange label.
  */
 export declare function transactionKind(key: string): TransactionKind;
+/** Dutch status names, for the same server-side readers as {@link TransactionKind.name}. */
+export declare const STATUS_NAMES: Record<TransactionStatus, string>;
+/** Where a person may move this document from its current status. Empty on a draft's issue. */
+export declare function nextStatuses(kindKey: string, from: TransactionStatus): readonly TransactionStatus[];
+export declare function canTransition(kindKey: string, from: TransactionStatus, to: TransactionStatus): boolean;

package/dist/entities/transaction/payment-term.d.ts

@@ -44,14 +44,6 @@ export interface PaymentTerm {
  * would make the answer depend on which timezone the server happened to be in.
  */
 export declare function dueDateFrom(issuedAt: number, dueDays: number): number;
-/**
- * The term that applies, out of the shared table and one administration's own.
- *
- * Shared rows first, then the administration's over them, by code — the same `shadowByKey` the VAT
- * table uses. Kept in domain rather than in the app because both the server and the screen have to
- * land on the same answer.
- */
-export declare function shadowTermsByCode(rows: readonly PaymentTerm[], businessEntityId?: string): PaymentTerm[];
 /**
  * The condition as it was copied onto a document.
  *

package/dist/entities/transaction/types.d.ts

@@ -1,4 +1,7 @@
+import { DocumentBlock } from '../../platform/document-blocks';
+import { DocumentSender } from '../document-template/types';
 import { Cents } from '../money/money';
+import { TaxRateKind } from '../money/tax';
 import { OwnerScope } from '../scope/types';
 import { TransactionPaymentTerm } from './payment-term';
 /**
@@ -95,6 +98,12 @@ export interface Transaction {
     expiresAt?: number;
     /** Only on a numbered kind, and only at the moment of issuing. */
     number?: string;
+    /**
+     * The paper as it went out: blocks and letterhead, filled at issue. A frozen document shows
+     * this and never re-renders — the customer's address, the sender's IBAN, a VAT rate and the
+     * template may all change afterwards, and an invoice must keep saying what it said.
+     */
+    issuedPaper?: IssuedPaper;
     /** Posted — to whichever set of books. Set by the push, never by a person. */
     postedAt?: number;
     /** The rendered PDF in `apps/storage`. A reference, never the content. */
@@ -126,7 +135,15 @@ export interface Transaction {
  * A union and not a free string: kinds and their statuses are **ours**, not the organisation's.
  * Labels follow from the key as `status_<key>`.
  */
-export type TransactionStatus = "draft" | "sent" | "accepted" | "rejected" | "expired" | "confirmed" | "delivered" | "open" | "paid" | "overdue" | "settled" | "cancelled";
+export type TransactionStatus = "draft" | "sent" | "accepted" | "rejected" | "expired" | "confirmed" | "delivered" | "open" | "paid" | "overdue" | "settled" | "cancelled"
+/** A newer version of this document went out. Set by the server, never by a person. */
+ | "superseded";
+export interface IssuedPaper {
+    blocks: DocumentBlock[];
+    sender: DocumentSender;
+    templateId?: string;
+    customerName?: string;
+}
 export interface TransactionLine {
     /** Stable within the transaction, so a version diff can follow a line. */
     id: string;
@@ -178,6 +195,9 @@ export interface TransactionTotals {
     /** Per rate, because that is what the invoice and the bookkeeping both need. */
     byRate: {
         taxRateKey: string;
+        /** As it was when priced. Absent on rows priced before it was stored. */
+        percent?: number;
+        kind?: TaxRateKind;
         netCents: Cents;
         taxCents: Cents;
     }[];

package/dist/entities/webhook/types.d.ts

@@ -5,7 +5,13 @@
  */
 export type WebhookMethod = "POST" | "PUT";
 export type WebhookContentType = "json" | "multipart";
-export type WebhookTrigger = "interactions:created" | "interactions:updated" | "activities:created" | "activities:updated";
+/**
+ * The bus events a webhook can listen to — full names, the same string as a rule's
+ * `Trigger.event.name`. Add one here and the automations app subscribes to it.
+ */
+export declare const WEBHOOK_EVENTS: readonly ["communication:interactions:created", "communication:interactions:updated", "communication:activities:created", "communication:activities:updated"];
+export type WebhookTrigger = (typeof WEBHOOK_EVENTS)[number];
+export declare function isWebhookEvent(value: unknown): value is WebhookTrigger;
 export interface Webhook {
     id: string;
     organizationId: string;

package/dist/entities/work/index.d.ts

@@ -4,3 +4,5 @@ export * from './item-types';
 export * from './keys';
 export * from './ladder';
 export * from './types';
+export * from './view';
+export * from './recurrence';

package/dist/entities/work/ladder.d.ts

@@ -104,3 +104,6 @@ export declare function validateStatuses(statuses: readonly WorkStatus[]): Statu
  * move nobody can unblock.
  */
 export declare function statusRequiresApproval(statusKey: string, ladder: readonly WorkStatus[]): boolean;
+/** How an item ended, read off its project's resolution flag. `undefined` = open or neither. */
+export type WorkOutcome = "won" | "lost";
+export declare function outcomeOf(resolution: string | undefined, project?: WorkProject | null): WorkOutcome | undefined;

package/dist/entities/work/recurrence.d.ts

@@ -0,0 +1,26 @@
+/**
+ * A repeating item: closing it makes the next one, the Asana "on completion" model. No schedule
+ * and no cron — the next occurrence exists the moment this one is done, so nothing can be missed
+ * by a job that did not run.
+ */
+export interface WorkRecurrence {
+    every: "day" | "week" | "month";
+    /** Every `interval` units; 1 = every week, 2 = every other week. */
+    interval: number;
+}
+/** A recurrence as a body sent it, or `undefined` when it is not one. */
+export declare function parseRecurrence(raw: unknown): WorkRecurrence | undefined;
+/** `ms` moved on by one recurrence step, in local calendar terms (a month is a month). */
+export declare function stepDate(ms: number, recurrence: WorkRecurrence): number;
+/**
+ * The next occurrence's dates. From the old due date when it had one (a weekly report stays on
+ * Friday even when finished on Monday), else from when it was closed. The start keeps its
+ * distance to the due date.
+ */
+export declare function nextOccurrenceDates(item: {
+    dueDate?: number;
+    startDate?: number;
+}, recurrence: WorkRecurrence, closedAt: number): {
+    dueDate: number;
+    startDate?: number;
+};

package/dist/entities/work/recurrence.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/entities/work/types.d.ts

@@ -1,3 +1,4 @@
+import { WorkRecurrence } from './recurrence';
 import { Relation } from '../../platform/resource-source';
 import { OwnerScope } from '../scope/types';
 /**
@@ -61,15 +62,16 @@ export interface WorkStatus {
 /**
  * A resolution: *how* something ended, apart from where it sits.
  *
- * Deliberately a free label with no fixed meaning and no outcome flag. A law firm distinguishes
- * "settled" from "judgment", a sales team "won" from "lost", and neither fits an enum we invent.
- * The price is in the plan: nothing can compute how much ended well. If that question comes, a
- * `positive?: boolean` belongs here.
+ * A free label: a law firm distinguishes "settled" from "judgment", a sales team "won" from
+ * "lost", and neither fits an enum we invent. `positive` is the one meaning a query may read —
+ * whether it ended well — so a win rate never guesses which label means good.
  */
 export interface WorkResolution {
     key: string;
     label: string;
     order: number;
+    /** `true` ended well, `false` ended badly, absent says neither (postponed, transferred). */
+    positive?: boolean;
 }
 /**
  * An item kind: an icon with a label, never a workflow.
@@ -227,18 +229,32 @@ export interface WorkCycle {
     committedSeconds?: number;
     /** Written once, when the cycle is completed. See {@link WorkCycleSummary}. */
     summary?: WorkCycleSummary;
+    /** One point per day while it runs, for the burndown. See {@link WorkCycleDay}. */
+    series?: WorkCycleDay[];
     /** Ids of this cycle in source systems. Empty on one created here. */
     externalIds?: string[];
     createdBy: string;
     createdAt?: number;
     updatedAt?: number;
 }
+/**
+ * Where a running cycle stood on one day. The hourly job overwrites today's point, so the last
+ * one of a day is what that day ended on; a day the job missed is simply absent (a gap, never an
+ * invented value). Embedded on the cycle: a sprint has a few dozen days, never thousands.
+ */
+export interface WorkCycleDay {
+    /** Start of the day, epoch ms (UTC). */
+    day: number;
+    open: number;
+    openSeconds: number;
+    done: number;
+}
 /**
  * What a cycle delivered, frozen at completion.
  *
- * One row written once, not a nightly snapshot: items move, so a burndown needs a daily series —
- * but "what did this team get done in the last eight cycles" needs eight rows and no rollup at
- * all. Compare against {@link WorkCycle.committedCount}, which was counted at the start.
+ * One row written once: "what did this team get done in the last eight cycles" needs eight rows
+ * and no rollup. The day-by-day view is {@link WorkCycle.series}. Compare against
+ * {@link WorkCycle.committedCount}, which was counted at the start.
  */
 export interface WorkCycleSummary {
     completed: number;
@@ -389,6 +405,10 @@ export interface WorkItem {
     dueDate?: number;
     /** Set as soon as the status moves to category `done`, cleared when it comes back. */
     closedAt?: number;
+    /** Closing makes the next one; see `WorkRecurrence`. */
+    recurrence?: WorkRecurrence;
+    /** The occurrence this one's closing made: set once, so a reopen-and-close makes no second. */
+    nextOccurrenceId?: string;
     estimateSeconds?: number;
     /**
      * Keys of the still-open items this one is `blocked_by`. **A read-time projection**, never

package/dist/entities/work/view.d.ts

@@ -0,0 +1,27 @@
+import { SavedView, SavedViewSort } from '../saved-view/types';
+/**
+ * Work's saved view: a {@link SavedView} over work items, optionally pinned to one project.
+ * The filter keys are declared once, here; the filter bar, the server's cleaning and the
+ * stored shape all derive from these two lists, so a new filter is one edit, not four.
+ */
+/** Multi-value filters: empty or absent = no filter on that axis. */
+export declare const WORK_VIEW_LIST_FILTERS: readonly ["statusKeys", "typeKeys", "labels", "priority", "assignees"];
+export type WorkViewListFilter = (typeof WORK_VIEW_LIST_FILTERS)[number];
+/**
+ * On/off filters. `watchingOnly` and `reportedByMe` are about the viewer, so the server resolves
+ * them; the bar only shows `blockedOnly`.
+ */
+export declare const WORK_VIEW_FLAGS: readonly ["blockedOnly", "watchingOnly", "reportedByMe"];
+export type WorkViewFlag = (typeof WORK_VIEW_FLAGS)[number];
+export type WorkViewFilters = {
+    search?: string;
+} & Partial<Record<WorkViewListFilter, string[]>> & Partial<Record<WorkViewFlag, boolean>>;
+export declare const WORK_SORT_FIELDS: readonly ["priority", "dueDate", "updatedAt", "createdAt", "title", "estimateSeconds"];
+export type WorkSortField = (typeof WORK_SORT_FIELDS)[number];
+export type WorkViewSort = SavedViewSort<WorkSortField>;
+export declare const WORK_VIEW_LAYOUTS: readonly ["list", "board", "calendar", "workload"];
+export type WorkViewLayout = (typeof WORK_VIEW_LAYOUTS)[number];
+export type WorkView = SavedView<WorkViewFilters, WorkViewLayout, WorkSortField> & {
+    /** Pinned to one project; absent = across everything the viewer can see. */
+    projectId?: string;
+};