@endora-commerce/contracts 0.108.0 → 0.109.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/admin-actions.d.ts +12 -3
- package/dist/admin-actions.d.ts.map +1 -1
- package/dist/admin-actions.js +34 -3
- package/dist/admin-actions.js.map +1 -1
- package/dist/admin-contributions.d.ts +35 -6
- package/dist/admin-contributions.d.ts.map +1 -1
- package/dist/admin-contributions.js +46 -0
- package/dist/admin-contributions.js.map +1 -1
- package/dist/admin-notifications.d.ts +17 -1
- package/dist/admin-notifications.d.ts.map +1 -1
- package/dist/admin-preferences.d.ts +108 -0
- package/dist/admin-preferences.d.ts.map +1 -0
- package/dist/admin-preferences.js +133 -0
- package/dist/admin-preferences.js.map +1 -0
- package/dist/admin.d.ts +15 -1
- package/dist/admin.d.ts.map +1 -1
- package/dist/admin.js +7 -0
- package/dist/admin.js.map +1 -1
- package/dist/assets-library.d.ts +97 -3
- package/dist/assets-library.d.ts.map +1 -1
- package/dist/assets-library.js +5 -0
- package/dist/assets-library.js.map +1 -1
- package/dist/blog.d.ts +57 -0
- package/dist/blog.d.ts.map +1 -1
- package/dist/blog.js +63 -1
- package/dist/blog.js.map +1 -1
- package/dist/carts.d.ts +113 -56
- package/dist/carts.d.ts.map +1 -1
- package/dist/carts.js +66 -13
- package/dist/carts.js.map +1 -1
- package/dist/catalog.d.ts +273 -34
- package/dist/catalog.d.ts.map +1 -1
- package/dist/catalog.js +256 -20
- package/dist/catalog.js.map +1 -1
- package/dist/cms-brand.d.ts +2233 -0
- package/dist/cms-brand.d.ts.map +1 -0
- package/dist/cms-brand.js +311 -0
- package/dist/cms-brand.js.map +1 -0
- package/dist/cms-contact-form.d.ts +55 -0
- package/dist/cms-contact-form.d.ts.map +1 -0
- package/dist/cms-contact-form.js +100 -0
- package/dist/cms-contact-form.js.map +1 -0
- package/dist/cms.d.ts +537 -3
- package/dist/cms.d.ts.map +1 -1
- package/dist/cms.js +251 -0
- package/dist/cms.js.map +1 -1
- package/dist/crm-rich-text.d.ts +10 -61
- package/dist/crm-rich-text.d.ts.map +1 -1
- package/dist/crm-rich-text.js +10 -300
- package/dist/crm-rich-text.js.map +1 -1
- package/dist/crm.d.ts +110 -82
- package/dist/crm.d.ts.map +1 -1
- package/dist/crm.js +29 -88
- package/dist/crm.js.map +1 -1
- package/dist/custom-fields.d.ts +27 -9
- package/dist/custom-fields.d.ts.map +1 -1
- package/dist/custom-fields.js +6 -0
- package/dist/custom-fields.js.map +1 -1
- package/dist/customer-accounts.d.ts +30 -0
- package/dist/customer-accounts.d.ts.map +1 -1
- package/dist/customer-accounts.js +31 -0
- package/dist/customer-accounts.js.map +1 -1
- package/dist/document-templates.d.ts +27 -15
- package/dist/document-templates.d.ts.map +1 -1
- package/dist/document-values.d.ts +8 -0
- package/dist/document-values.d.ts.map +1 -1
- package/dist/document-values.js +24 -6
- package/dist/document-values.js.map +1 -1
- package/dist/email.d.ts +5 -0
- package/dist/email.d.ts.map +1 -1
- package/dist/errors.d.ts +105 -0
- package/dist/errors.d.ts.map +1 -1
- package/dist/errors.js +123 -0
- package/dist/errors.js.map +1 -1
- package/dist/index.d.ts +13 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +27 -1
- package/dist/index.js.map +1 -1
- package/dist/inventory.d.ts +3 -3
- package/dist/invoices.d.ts +6 -2
- package/dist/invoices.d.ts.map +1 -1
- package/dist/invoices.js +3 -0
- package/dist/invoices.js.map +1 -1
- package/dist/megamenu.d.ts +674 -0
- package/dist/megamenu.d.ts.map +1 -1
- package/dist/megamenu.js +96 -3
- package/dist/megamenu.js.map +1 -1
- package/dist/mfa.d.ts +1 -0
- package/dist/mfa.d.ts.map +1 -1
- package/dist/mfa.js +8 -2
- package/dist/mfa.js.map +1 -1
- package/dist/modules.d.ts +8 -1
- package/dist/modules.d.ts.map +1 -1
- package/dist/modules.js +5 -0
- package/dist/modules.js.map +1 -1
- package/dist/newsletter.d.ts +3 -3
- package/dist/orders.d.ts +25 -0
- package/dist/orders.d.ts.map +1 -1
- package/dist/orders.js +14 -0
- package/dist/orders.js.map +1 -1
- package/dist/page-builder-props.d.ts +1401 -0
- package/dist/page-builder-props.d.ts.map +1 -0
- package/dist/page-builder-props.js +266 -0
- package/dist/page-builder-props.js.map +1 -0
- package/dist/page-builder-values.d.ts +95 -0
- package/dist/page-builder-values.d.ts.map +1 -0
- package/dist/page-builder-values.js +164 -0
- package/dist/page-builder-values.js.map +1 -0
- package/dist/pim-connector.d.ts +1 -1
- package/dist/platform-language.d.ts +9 -0
- package/dist/platform-language.d.ts.map +1 -1
- package/dist/platform-language.js +14 -0
- package/dist/platform-language.js.map +1 -1
- package/dist/price-books.d.ts +60 -60
- package/dist/price-lists.d.ts +44 -10
- package/dist/price-lists.d.ts.map +1 -1
- package/dist/price-lists.js +24 -1
- package/dist/price-lists.js.map +1 -1
- package/dist/product-feeds.d.ts +115 -55
- package/dist/product-feeds.d.ts.map +1 -1
- package/dist/product-feeds.js +18 -0
- package/dist/product-feeds.js.map +1 -1
- package/dist/product-scopes.d.ts +628 -0
- package/dist/product-scopes.d.ts.map +1 -0
- package/dist/product-scopes.js +365 -0
- package/dist/product-scopes.js.map +1 -0
- package/dist/product-summary-text.d.ts +23 -0
- package/dist/product-summary-text.d.ts.map +1 -0
- package/dist/product-summary-text.js +64 -0
- package/dist/product-summary-text.js.map +1 -0
- package/dist/product-url-keys.d.ts +204 -0
- package/dist/product-url-keys.d.ts.map +1 -0
- package/dist/product-url-keys.js +166 -0
- package/dist/product-url-keys.js.map +1 -0
- package/dist/projects.d.ts +2355 -0
- package/dist/projects.d.ts.map +1 -0
- package/dist/projects.js +837 -0
- package/dist/projects.js.map +1 -0
- package/dist/prompt-actions.d.ts +19 -1
- package/dist/prompt-actions.d.ts.map +1 -1
- package/dist/prompt-actions.js +31 -2
- package/dist/prompt-actions.js.map +1 -1
- package/dist/quick-order.d.ts +0 -1
- package/dist/quick-order.d.ts.map +1 -1
- package/dist/quick-order.js +1 -1
- package/dist/quick-order.js.map +1 -1
- package/dist/quote-requests.d.ts +36 -1
- package/dist/quote-requests.d.ts.map +1 -1
- package/dist/quote-requests.js +24 -0
- package/dist/quote-requests.js.map +1 -1
- package/dist/record-references.d.ts +252 -0
- package/dist/record-references.d.ts.map +1 -0
- package/dist/record-references.js +179 -0
- package/dist/record-references.js.map +1 -0
- package/dist/record-rich-text.d.ts +66 -0
- package/dist/record-rich-text.d.ts.map +1 -0
- package/dist/record-rich-text.js +303 -0
- package/dist/record-rich-text.js.map +1 -0
- package/dist/returns.d.ts +26 -0
- package/dist/returns.d.ts.map +1 -1
- package/dist/sales-channels.d.ts +51 -7
- package/dist/sales-channels.d.ts.map +1 -1
- package/dist/sales-channels.js +38 -4
- package/dist/sales-channels.js.map +1 -1
- package/dist/saved-list-views.d.ts +28 -0
- package/dist/saved-list-views.d.ts.map +1 -1
- package/dist/saved-list-views.js +14 -1
- package/dist/saved-list-views.js.map +1 -1
- package/dist/scoped-translations.d.ts +48 -0
- package/dist/scoped-translations.d.ts.map +1 -0
- package/dist/scoped-translations.js +78 -0
- package/dist/scoped-translations.js.map +1 -0
- package/dist/search.d.ts +15 -7
- package/dist/search.d.ts.map +1 -1
- package/dist/seo.d.ts +64 -5
- package/dist/seo.d.ts.map +1 -1
- package/dist/seo.js +31 -4
- package/dist/seo.js.map +1 -1
- package/dist/settings.d.ts +32 -3
- package/dist/settings.d.ts.map +1 -1
- package/dist/settings.js +37 -3
- package/dist/settings.js.map +1 -1
- package/dist/storefront-cache-tags.d.ts +29 -0
- package/dist/storefront-cache-tags.d.ts.map +1 -1
- package/dist/storefront-cache-tags.js +24 -0
- package/dist/storefront-cache-tags.js.map +1 -1
- package/dist/storefront-language-path.d.ts +77 -0
- package/dist/storefront-language-path.d.ts.map +1 -0
- package/dist/storefront-language-path.js +123 -0
- package/dist/storefront-language-path.js.map +1 -0
- package/dist/tasks.d.ts +2842 -0
- package/dist/tasks.d.ts.map +1 -0
- package/dist/tasks.js +901 -0
- package/dist/tasks.js.map +1 -0
- package/dist/transactional-emails.d.ts +7 -4
- package/dist/transactional-emails.d.ts.map +1 -1
- package/dist/transactional-emails.js +13 -0
- package/dist/transactional-emails.js.map +1 -1
- package/package.json +2 -2
package/dist/projects.js
ADDED
|
@@ -0,0 +1,837 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
import { calendarDateSchema } from './common.js';
|
|
3
|
+
import { dataEnvelope } from './envelopes.js';
|
|
4
|
+
import { customFieldFiltersQueryParamSchema, customFieldValuesSchema } from './custom-fields.js';
|
|
5
|
+
import { twoDecimalAmountString } from './money-input.js';
|
|
6
|
+
import { RecordReferenceSchema } from './record-references.js';
|
|
7
|
+
import { TaskSummarySchema } from './tasks.js';
|
|
8
|
+
/**
|
|
9
|
+
* Projects (`specs/163-projects-and-tasks/`).
|
|
10
|
+
*
|
|
11
|
+
* Every request, response, port, registry and event shape of the `projects`
|
|
12
|
+
* module, written before the first route (Constitution II) and for **every**
|
|
13
|
+
* story of the feature — later phases add no contract here. The normative prose
|
|
14
|
+
* is `specs/163-projects-and-tasks/contracts/admin-api.md` §2 and
|
|
15
|
+
* `contracts/ports-and-events.md` §2; the schema is `data-model.md` §2.
|
|
16
|
+
*
|
|
17
|
+
* A Project that is out of the caller's Organization reach, or invisible to
|
|
18
|
+
* them, answers 404 `PROJECT_NOT_FOUND` — identical to one that does not exist
|
|
19
|
+
* (FR-004, FR-020, Constitution XI).
|
|
20
|
+
*
|
|
21
|
+
* Base path of the HTTP API: `/api/v1/admin/projects`. There is no storefront
|
|
22
|
+
* or customer route (FR-043).
|
|
23
|
+
*/
|
|
24
|
+
// ---------------------------------------------------------------------------
|
|
25
|
+
// Vocabulary and limits
|
|
26
|
+
// ---------------------------------------------------------------------------
|
|
27
|
+
/** A Project's outcome. `open` while it runs; a closed Project can be reopened. */
|
|
28
|
+
export const PROJECT_STATES = ['open', 'completed', 'lost'];
|
|
29
|
+
export const projectStateSchema = z.enum(PROJECT_STATES);
|
|
30
|
+
/** How a closed Project ended — the `close` body's discriminant. */
|
|
31
|
+
export const projectOutcomeSchema = z.enum(['completed', 'lost']);
|
|
32
|
+
/**
|
|
33
|
+
* A Project's own visibility (owner ruling Q2 = A, FR-019): follow the module
|
|
34
|
+
* setting, everyone who may read Projects, or its Members and the people listed
|
|
35
|
+
* on it.
|
|
36
|
+
*/
|
|
37
|
+
export const projectVisibilitySchema = z.enum(['inherit', 'everyone', 'members_and_listed']);
|
|
38
|
+
/** The module setting `projects.visibility` (FR-018); default `members`. */
|
|
39
|
+
export const projectVisibilitySettingSchema = z.enum(['everyone', 'members']);
|
|
40
|
+
/** What a Project links to (R-10). */
|
|
41
|
+
export const projectRecordKindSchema = z.enum(['order', 'quote_request', 'opportunity']);
|
|
42
|
+
/** The records whose screen shows "which Project is this in" — the link kinds and a Task (R-11). */
|
|
43
|
+
export const projectPanelRecordKindSchema = z.enum(['order', 'quote_request', 'opportunity', 'task']);
|
|
44
|
+
export const projectCommentKindSchema = z.enum(['note', 'message']);
|
|
45
|
+
/** What a Stage-history row records (`project_stage_entries.kind`). */
|
|
46
|
+
export const projectStageEntryKindSchema = z.enum(['enter', 'close_completed', 'close_lost', 'reopen']);
|
|
47
|
+
/** What a move recorded beside itself (R-8). */
|
|
48
|
+
export const projectStageEntryNoteSchema = z.enum([
|
|
49
|
+
'gate_not_applied_tasks_off',
|
|
50
|
+
'stage_tasks_skipped',
|
|
51
|
+
'tasks_materialize_failed',
|
|
52
|
+
]);
|
|
53
|
+
export const PROJECT_TITLE_MAX = 200;
|
|
54
|
+
export const PROJECT_DESCRIPTION_MAX = 20_000;
|
|
55
|
+
export const PROJECT_STAGE_NAME_MAX = 80;
|
|
56
|
+
export const PROJECT_STAGE_DURATION_MAX_DAYS = 3650;
|
|
57
|
+
export const PROJECT_ALERT_OFFSET_MIN_DAYS = 1;
|
|
58
|
+
export const PROJECT_ALERT_OFFSET_MAX_DAYS = 365;
|
|
59
|
+
export const PROJECT_LOSS_COMMENT_MAX = 2000;
|
|
60
|
+
export const PROJECT_COMMENT_BODY_MAX = 20_000;
|
|
61
|
+
export const PROJECT_TEMPLATE_NAME_MAX = 120;
|
|
62
|
+
export const PROJECT_DICTIONARY_NAME_MAX = 120;
|
|
63
|
+
/** The most Stage Task definitions one Stage holds (R-22). */
|
|
64
|
+
export const PROJECT_STAGE_TASKS_MAX = 100;
|
|
65
|
+
export const PROJECT_STAGES_MAX = 50;
|
|
66
|
+
export const PROJECT_LIST_LIMIT_MAX = 100;
|
|
67
|
+
/**
|
|
68
|
+
* The largest file `POST /projects/:id/attachments/upload` reads, in bytes
|
|
69
|
+
* (25 MB) — CRM's bound, for CRM's reason: the route holds the whole file in
|
|
70
|
+
* memory before the asset library decides anything about it.
|
|
71
|
+
*/
|
|
72
|
+
export const PROJECT_ATTACHMENT_MAX_BYTES = 25 * 1024 * 1024;
|
|
73
|
+
const uuid = z.string().uuid();
|
|
74
|
+
const isoTimestampSchema = z.string();
|
|
75
|
+
const colorSchema = z.string().regex(/^#[0-9a-fA-F]{6}$/, 'Colour must be a #rrggbb hex value');
|
|
76
|
+
const currencyCodeSchema = z.string().regex(/^[A-Z]{3}$/, 'Currency must be an ISO 4217 code, e.g. PLN');
|
|
77
|
+
/**
|
|
78
|
+
* A non-negative amount as a decimal string — `numeric(18,2)`; more than two
|
|
79
|
+
* decimal places is refused with the platform's precision code, never rounded
|
|
80
|
+
* (`money-input.ts`, issue #417).
|
|
81
|
+
*/
|
|
82
|
+
const amountSchema = twoDecimalAmountString(z.string().trim(), {
|
|
83
|
+
pattern: /^\d{1,16}(\.\d+)?$/,
|
|
84
|
+
message: 'Amount must be a non-negative decimal with at most two places',
|
|
85
|
+
});
|
|
86
|
+
const titleSchema = z.string().trim().min(1).max(PROJECT_TITLE_MAX);
|
|
87
|
+
const descriptionSchema = z.string().max(PROJECT_DESCRIPTION_MAX);
|
|
88
|
+
/** A list of ids in which each appears once. */
|
|
89
|
+
function distinctIds(max) {
|
|
90
|
+
return z
|
|
91
|
+
.array(uuid)
|
|
92
|
+
.max(max)
|
|
93
|
+
.refine((ids) => new Set(ids.map((id) => id.toLowerCase())).size === ids.length, {
|
|
94
|
+
message: 'Each id may appear once',
|
|
95
|
+
});
|
|
96
|
+
}
|
|
97
|
+
/**
|
|
98
|
+
* A query-string field that may repeat. One occurrence arrives as a string and
|
|
99
|
+
* several as an array; both normalise to an array.
|
|
100
|
+
*/
|
|
101
|
+
function repeatable(item) {
|
|
102
|
+
return z.preprocess((value) => (value === undefined || Array.isArray(value) ? value : [value]), z.array(item).max(50).optional());
|
|
103
|
+
}
|
|
104
|
+
/** A name per admin language (`{ en, pl }`), resolved with `pickLocalized`. */
|
|
105
|
+
const localizedNameSchema = z.record(z.string().min(2).max(16), z.string().trim().min(1).max(PROJECT_DICTIONARY_NAME_MAX));
|
|
106
|
+
// ---------------------------------------------------------------------------
|
|
107
|
+
// Field shapes shared by Projects and Templates
|
|
108
|
+
// ---------------------------------------------------------------------------
|
|
109
|
+
/** A value is an amount **and** its currency, or nothing (`data-model.md` §2.2). */
|
|
110
|
+
export const ProjectValueSchema = z
|
|
111
|
+
.object({
|
|
112
|
+
amount: amountSchema,
|
|
113
|
+
currency: currencyCodeSchema,
|
|
114
|
+
})
|
|
115
|
+
.strict();
|
|
116
|
+
/** Deadline alerts: whole days before the deadline, 1–365, each once (FR-010). */
|
|
117
|
+
export const alertOffsetsDaysSchema = z
|
|
118
|
+
.array(z.number().int().min(PROJECT_ALERT_OFFSET_MIN_DAYS).max(PROJECT_ALERT_OFFSET_MAX_DAYS))
|
|
119
|
+
.max(20)
|
|
120
|
+
.refine((offsets) => new Set(offsets).size === offsets.length, {
|
|
121
|
+
message: 'Each alert offset may appear once',
|
|
122
|
+
});
|
|
123
|
+
const plannedDurationDaysSchema = z.number().int().min(0).max(PROJECT_STAGE_DURATION_MAX_DAYS);
|
|
124
|
+
/** One Member and the Project Roles they hold (≥ 0 — a Member without a Role is allowed). */
|
|
125
|
+
export const ProjectMemberInputSchema = z
|
|
126
|
+
.object({
|
|
127
|
+
adminUserId: uuid,
|
|
128
|
+
roleIds: distinctIds(50),
|
|
129
|
+
})
|
|
130
|
+
.strict();
|
|
131
|
+
const membersSchema = z
|
|
132
|
+
.array(ProjectMemberInputSchema)
|
|
133
|
+
.max(200)
|
|
134
|
+
.refine((members) => new Set(members.map((m) => m.adminUserId.toLowerCase())).size === members.length, {
|
|
135
|
+
message: 'Each person may be a Member once',
|
|
136
|
+
});
|
|
137
|
+
/**
|
|
138
|
+
* A Stage Task definition — copied from a Template or written on the Project;
|
|
139
|
+
* it becomes a Task when the Project enters its Stage (R-7, R-8).
|
|
140
|
+
*/
|
|
141
|
+
export const StageTaskDefinitionSchema = z
|
|
142
|
+
.object({
|
|
143
|
+
title: z.string().trim().min(1).max(200),
|
|
144
|
+
description: z.string().max(PROJECT_DESCRIPTION_MAX).optional(),
|
|
145
|
+
responsibleRoleId: uuid.nullable().optional(),
|
|
146
|
+
/** Due date = the Stage's start + this many days. */
|
|
147
|
+
dueOffsetDays: z.number().int().min(0).max(PROJECT_STAGE_DURATION_MAX_DAYS),
|
|
148
|
+
})
|
|
149
|
+
.strict();
|
|
150
|
+
const stageTasksSchema = z.array(StageTaskDefinitionSchema).max(PROJECT_STAGE_TASKS_MAX);
|
|
151
|
+
/** The attributes of FR-010 a Stage has in a Project and in a Template alike. */
|
|
152
|
+
const stageAttributesShape = {
|
|
153
|
+
name: z.string().trim().min(1).max(PROJECT_STAGE_NAME_MAX),
|
|
154
|
+
color: colorSchema,
|
|
155
|
+
plannedDurationDays: plannedDurationDaysSchema.optional(),
|
|
156
|
+
responsibleRoleIds: distinctIds(50).optional(),
|
|
157
|
+
alertOffsetsDays: alertOffsetsDaysSchema.optional(),
|
|
158
|
+
completionGate: z.boolean().optional(),
|
|
159
|
+
completionPermitted: z.boolean().optional(),
|
|
160
|
+
};
|
|
161
|
+
// ---------------------------------------------------------------------------
|
|
162
|
+
// §2.1 Projects — requests
|
|
163
|
+
// ---------------------------------------------------------------------------
|
|
164
|
+
/** `memberId`: an admin user's id or `me`. */
|
|
165
|
+
const memberFilterSchema = z.union([z.literal('me'), uuid]);
|
|
166
|
+
export const ProjectListQuerySchema = z.object({
|
|
167
|
+
state: repeatable(projectStateSchema),
|
|
168
|
+
organizationId: uuid.optional(),
|
|
169
|
+
memberId: memberFilterSchema.optional(),
|
|
170
|
+
roleId: uuid.optional(),
|
|
171
|
+
templateId: uuid.optional(),
|
|
172
|
+
/** The current Stage's name, case-insensitive. */
|
|
173
|
+
stageName: z.string().trim().min(1).max(PROJECT_STAGE_NAME_MAX).optional(),
|
|
174
|
+
/** Number or title. */
|
|
175
|
+
q: z.string().trim().max(200).optional(),
|
|
176
|
+
/**
|
|
177
|
+
* Custom fields marked as list filters (User Story 9), as JSON — the shape
|
|
178
|
+
* the Orders, Quote Requests and Opportunities lists take. A field the list
|
|
179
|
+
* does not offer answers 400 `CUSTOM_FIELD_FILTER_UNAVAILABLE` naming it.
|
|
180
|
+
*/
|
|
181
|
+
customFieldFilters: customFieldFiltersQueryParamSchema,
|
|
182
|
+
sort: z.enum(['createdAt', 'value', 'deadline']).optional(),
|
|
183
|
+
order: z.enum(['asc', 'desc']).optional(),
|
|
184
|
+
cursor: z.string().optional(),
|
|
185
|
+
limit: z.coerce.number().int().positive().max(PROJECT_LIST_LIMIT_MAX).default(50),
|
|
186
|
+
});
|
|
187
|
+
/** A Stage written with the Project that holds it (`POST /projects`, `stages`). */
|
|
188
|
+
export const ProjectStageInputSchema = z.object(stageAttributesShape).strict();
|
|
189
|
+
/**
|
|
190
|
+
* `POST /projects`. `organizationIds` may be empty — an internal Project,
|
|
191
|
+
* visible only to administrators unrestricted in Organization reach (FR-004);
|
|
192
|
+
* each Organization must be in the caller's reach (422
|
|
193
|
+
* `PROJECT_ORGANIZATION_OUT_OF_SCOPE`). With a `templateId` the Template's
|
|
194
|
+
* structure is copied (R-7) and the body's own fields win.
|
|
195
|
+
*
|
|
196
|
+
* `stages` are the Project's Stages in order — an open Project is always in
|
|
197
|
+
* one, so without a Template at least one is required (422
|
|
198
|
+
* `VALIDATION_FAILED`). The Project starts in the first; the default workflow
|
|
199
|
+
* lets each move to the next (FR-011), and completing is permitted from the
|
|
200
|
+
* last unless a Stage says otherwise (FR-010).
|
|
201
|
+
*/
|
|
202
|
+
export const CreateProjectBodySchema = z
|
|
203
|
+
.object({
|
|
204
|
+
title: titleSchema,
|
|
205
|
+
stages: z.array(ProjectStageInputSchema).min(1).max(PROJECT_STAGES_MAX).optional(),
|
|
206
|
+
description: descriptionSchema.optional(),
|
|
207
|
+
value: ProjectValueSchema.nullable().optional(),
|
|
208
|
+
startOn: calendarDateSchema.optional(),
|
|
209
|
+
organizationIds: distinctIds(50),
|
|
210
|
+
templateId: uuid.optional(),
|
|
211
|
+
members: membersSchema.optional(),
|
|
212
|
+
visibility: projectVisibilitySchema.optional(),
|
|
213
|
+
viewerIds: distinctIds(200).optional(),
|
|
214
|
+
customFieldValues: customFieldValuesSchema.optional(),
|
|
215
|
+
})
|
|
216
|
+
.strict();
|
|
217
|
+
/**
|
|
218
|
+
* `PATCH /projects/:id`. Organizations and Members have routes of their own;
|
|
219
|
+
* `version` is the optimistic-concurrency token (409 `PROJECT_CHANGED`).
|
|
220
|
+
*/
|
|
221
|
+
export const UpdateProjectBodySchema = z
|
|
222
|
+
.object({
|
|
223
|
+
title: titleSchema.optional(),
|
|
224
|
+
description: descriptionSchema.optional(),
|
|
225
|
+
value: ProjectValueSchema.nullable().optional(),
|
|
226
|
+
startOn: calendarDateSchema.optional(),
|
|
227
|
+
visibility: projectVisibilitySchema.optional(),
|
|
228
|
+
viewerIds: distinctIds(200).optional(),
|
|
229
|
+
customFieldValues: customFieldValuesSchema.optional(),
|
|
230
|
+
version: z.number().int().positive(),
|
|
231
|
+
})
|
|
232
|
+
.strict();
|
|
233
|
+
/** `PUT /projects/:id/organizations` — the whole set (409 `PROJECT_ORGANIZATION_IN_USE`). */
|
|
234
|
+
export const SetProjectOrganizationsBodySchema = z
|
|
235
|
+
.object({ organizationIds: distinctIds(50) })
|
|
236
|
+
.strict();
|
|
237
|
+
/**
|
|
238
|
+
* The answer of `PUT /projects/:id/organizations` when the change the caller
|
|
239
|
+
* just made took the Project out of their own Organization reach — a caller
|
|
240
|
+
* confined to some Organizations who removed them all, making the Project
|
|
241
|
+
* internal (T144 F3). The change committed; nothing else of the Project is
|
|
242
|
+
* theirs to be shown.
|
|
243
|
+
*/
|
|
244
|
+
export const ProjectOutOfReachAfterWriteSchema = z.object({ id: uuid, outOfReach: z.literal(true) }).strict();
|
|
245
|
+
/** `PUT /projects/:id/members` — the whole set, Members and their Roles, in one Command. */
|
|
246
|
+
export const SetProjectMembersBodySchema = z.object({ members: membersSchema }).strict();
|
|
247
|
+
// ---------------------------------------------------------------------------
|
|
248
|
+
// §2.2 Stages and moves — requests
|
|
249
|
+
// ---------------------------------------------------------------------------
|
|
250
|
+
/** `POST /projects/:id/stages`. */
|
|
251
|
+
export const CreateProjectStageBodySchema = z.object(stageAttributesShape).strict();
|
|
252
|
+
/**
|
|
253
|
+
* `PATCH /projects/:id/stages/:stageId` — any attribute, at least one.
|
|
254
|
+
* `deadlineOn` sets the deadline by hand; `null` drops the manual deadline and
|
|
255
|
+
* recomputes it as start + planned duration (FR-013).
|
|
256
|
+
*/
|
|
257
|
+
export const UpdateProjectStageBodySchema = z
|
|
258
|
+
.object({ ...stageAttributesShape, deadlineOn: calendarDateSchema.nullable() })
|
|
259
|
+
.partial()
|
|
260
|
+
.strict()
|
|
261
|
+
.refine((body) => Object.keys(body).length > 0, { message: 'Nothing to change' });
|
|
262
|
+
/** `PUT /projects/:id/stages/order` — every Stage id of the Project, in the new order. */
|
|
263
|
+
export const ReorderProjectStagesBodySchema = z
|
|
264
|
+
.object({ stageIds: distinctIds(PROJECT_STAGES_MAX).refine((ids) => ids.length > 0, 'At least one Stage') })
|
|
265
|
+
.strict();
|
|
266
|
+
export const ProjectStageMoveSchema = z
|
|
267
|
+
.object({ fromStageId: uuid, toStageId: uuid })
|
|
268
|
+
.strict()
|
|
269
|
+
.refine((move) => move.fromStageId.toLowerCase() !== move.toStageId.toLowerCase(), {
|
|
270
|
+
message: 'A move must connect two different Stages',
|
|
271
|
+
});
|
|
272
|
+
/** `PUT /projects/:id/moves` — the whole set of permitted moves (FR-011). */
|
|
273
|
+
export const SetProjectMovesBodySchema = z
|
|
274
|
+
.object({ moves: z.array(ProjectStageMoveSchema).max(PROJECT_STAGES_MAX * PROJECT_STAGES_MAX) })
|
|
275
|
+
.strict();
|
|
276
|
+
/** `PUT /projects/:id/stages/:stageId/tasks` — the Stage's Task definitions, replaced whole. */
|
|
277
|
+
export const SetProjectStageTasksBodySchema = z.object({ tasks: stageTasksSchema }).strict();
|
|
278
|
+
/** `POST /projects/:id/move`. */
|
|
279
|
+
export const MoveProjectBodySchema = z
|
|
280
|
+
.object({ toStageId: uuid, version: z.number().int().positive() })
|
|
281
|
+
.strict();
|
|
282
|
+
/**
|
|
283
|
+
* `POST /projects/:id/close` — discriminated on `outcome`. Completing needs a
|
|
284
|
+
* Stage that permits it and passes its gate; losing is allowed from any Stage,
|
|
285
|
+
* needs a non-archived loss reason and is never gated (FR-005, FR-012).
|
|
286
|
+
*/
|
|
287
|
+
export const CloseProjectBodySchema = z.discriminatedUnion('outcome', [
|
|
288
|
+
z.object({ outcome: z.literal('completed'), version: z.number().int().positive() }).strict(),
|
|
289
|
+
z
|
|
290
|
+
.object({
|
|
291
|
+
outcome: z.literal('lost'),
|
|
292
|
+
lossReasonId: uuid,
|
|
293
|
+
comment: z.string().trim().max(PROJECT_LOSS_COMMENT_MAX).optional(),
|
|
294
|
+
version: z.number().int().positive(),
|
|
295
|
+
})
|
|
296
|
+
.strict(),
|
|
297
|
+
]);
|
|
298
|
+
/** `POST /projects/:id/reopen` — back into the Stage it was closed in (FR-006). */
|
|
299
|
+
export const ReopenProjectBodySchema = z.object({ version: z.number().int().positive() }).strict();
|
|
300
|
+
// ---------------------------------------------------------------------------
|
|
301
|
+
// §2.3 Links and the record panel — requests
|
|
302
|
+
// ---------------------------------------------------------------------------
|
|
303
|
+
/** `POST /projects/:id/links`. */
|
|
304
|
+
export const CreateProjectLinkBodySchema = z
|
|
305
|
+
.object({ kind: projectRecordKindSchema, recordId: uuid })
|
|
306
|
+
.strict();
|
|
307
|
+
/** `GET /projects/records/:kind/:recordId/project` — the path parameters. */
|
|
308
|
+
export const RecordProjectParamsSchema = z.object({
|
|
309
|
+
kind: projectPanelRecordKindSchema,
|
|
310
|
+
recordId: uuid,
|
|
311
|
+
});
|
|
312
|
+
// ---------------------------------------------------------------------------
|
|
313
|
+
// §2.4 Collaboration — requests
|
|
314
|
+
// ---------------------------------------------------------------------------
|
|
315
|
+
const commentBodySchema = z.string().min(1).max(PROJECT_COMMENT_BODY_MAX);
|
|
316
|
+
export const ProjectCommentListQuerySchema = z.object({ kind: projectCommentKindSchema });
|
|
317
|
+
export const CreateProjectCommentBodySchema = z
|
|
318
|
+
.object({ kind: projectCommentKindSchema, body: commentBodySchema })
|
|
319
|
+
.strict();
|
|
320
|
+
/** `PATCH /projects/:id/comments/:commentId` — a note, by its author; a message never changes. */
|
|
321
|
+
export const UpdateProjectCommentBodySchema = z.object({ body: commentBodySchema }).strict();
|
|
322
|
+
/**
|
|
323
|
+
* `POST /projects/:id/messages/read` — the caller has read the thread up to and
|
|
324
|
+
* including this message. Named by the message, so no browser clock is in it.
|
|
325
|
+
*/
|
|
326
|
+
export const MarkProjectMessagesReadBodySchema = z.object({ throughMessageId: uuid }).strict();
|
|
327
|
+
/** `POST /projects/:id/attachments` — a private, live asset that is not active content. */
|
|
328
|
+
export const CreateProjectAttachmentBodySchema = z.object({ assetId: uuid }).strict();
|
|
329
|
+
const lookupSearchSchema = z.string().trim().max(200).optional();
|
|
330
|
+
/** `GET /projects/lookups/mentionable` — people who could see the Project (R-4). */
|
|
331
|
+
export const ProjectMentionableLookupQuerySchema = z.object({
|
|
332
|
+
projectId: uuid.optional(),
|
|
333
|
+
q: lookupSearchSchema,
|
|
334
|
+
});
|
|
335
|
+
/**
|
|
336
|
+
* `GET /projects/lookups/documents` — the `@@` list; answered with
|
|
337
|
+
* `RecordDocumentLookupResponseSchema` of `record-references.ts` (FR-044).
|
|
338
|
+
* Without a `projectId` (a Project being created) Orders and Quote Requests of
|
|
339
|
+
* no Organization are offered — none.
|
|
340
|
+
*/
|
|
341
|
+
export const ProjectDocumentLookupQuerySchema = z.object({
|
|
342
|
+
projectId: uuid.optional(),
|
|
343
|
+
/**
|
|
344
|
+
* Before a Project exists (the create form): the Organizations chosen on the
|
|
345
|
+
* form, whose Orders and Quote Requests are offered — only those within the
|
|
346
|
+
* caller's reach count. Ignored beside `projectId`, whose Project's
|
|
347
|
+
* Organizations are the answer.
|
|
348
|
+
*/
|
|
349
|
+
organizationIds: repeatable(uuid),
|
|
350
|
+
q: lookupSearchSchema,
|
|
351
|
+
});
|
|
352
|
+
/** At most this many options per lookup answer. */
|
|
353
|
+
const lookupLimitSchema = z.coerce.number().int().positive().max(50).default(20);
|
|
354
|
+
/**
|
|
355
|
+
* `GET /projects/lookups/organizations` — the Organizations the caller may
|
|
356
|
+
* name on a Project, by name (`q`), or one by `id` (the label of a value chosen
|
|
357
|
+
* earlier). Only Organizations in the caller's reach are ever answered.
|
|
358
|
+
*/
|
|
359
|
+
export const ProjectOrganizationLookupQuerySchema = z.object({
|
|
360
|
+
q: lookupSearchSchema,
|
|
361
|
+
id: uuid.optional(),
|
|
362
|
+
limit: lookupLimitSchema,
|
|
363
|
+
});
|
|
364
|
+
/**
|
|
365
|
+
* `GET /projects/lookups/admin-users` — active administrators by name or
|
|
366
|
+
* e-mail (`q`), or one by `id` — who may be a Member or a listed person.
|
|
367
|
+
*/
|
|
368
|
+
export const ProjectAdminUserLookupQuerySchema = z.object({
|
|
369
|
+
q: lookupSearchSchema,
|
|
370
|
+
id: uuid.optional(),
|
|
371
|
+
limit: lookupLimitSchema,
|
|
372
|
+
});
|
|
373
|
+
// ---------------------------------------------------------------------------
|
|
374
|
+
// §2.5 Configuration — requests
|
|
375
|
+
// ---------------------------------------------------------------------------
|
|
376
|
+
/**
|
|
377
|
+
* `GET /projects/roles`, `GET /projects/loss-reasons`. `active=true` leaves
|
|
378
|
+
* archived rows out — what a picker offers; without it every row is listed,
|
|
379
|
+
* archived ones included, because a Project still shows the ones it uses.
|
|
380
|
+
*/
|
|
381
|
+
export const ProjectDictionaryListQuerySchema = z.object({
|
|
382
|
+
active: z.enum(['true', 'false']).optional(),
|
|
383
|
+
});
|
|
384
|
+
/** A Project Role or a loss reason — names per language and a fallback. */
|
|
385
|
+
const dictionaryEntryShape = {
|
|
386
|
+
name: localizedNameSchema,
|
|
387
|
+
defaultName: z.string().trim().min(1).max(PROJECT_DICTIONARY_NAME_MAX),
|
|
388
|
+
};
|
|
389
|
+
/** `POST /projects/roles`. The code is derived from the default name. */
|
|
390
|
+
export const CreateProjectRoleBodySchema = z.object(dictionaryEntryShape).strict();
|
|
391
|
+
/** `PATCH /projects/roles/:id` — renaming; the code never changes. */
|
|
392
|
+
export const UpdateProjectRoleBodySchema = z
|
|
393
|
+
.object(dictionaryEntryShape)
|
|
394
|
+
.partial()
|
|
395
|
+
.strict()
|
|
396
|
+
.refine((body) => Object.keys(body).length > 0, { message: 'Nothing to change' });
|
|
397
|
+
export const CreateProjectLossReasonBodySchema = z.object(dictionaryEntryShape).strict();
|
|
398
|
+
export const UpdateProjectLossReasonBodySchema = z
|
|
399
|
+
.object(dictionaryEntryShape)
|
|
400
|
+
.partial()
|
|
401
|
+
.strict()
|
|
402
|
+
.refine((body) => Object.keys(body).length > 0, { message: 'Nothing to change' });
|
|
403
|
+
/**
|
|
404
|
+
* A Template's Stage in the whole-graph body. `key` names the Stage inside the
|
|
405
|
+
* body — an existing Stage's id, or any label the editor chose for a new one —
|
|
406
|
+
* so a move can name a Stage that has no id yet.
|
|
407
|
+
*/
|
|
408
|
+
export const ProjectTemplateStageInputSchema = z
|
|
409
|
+
.object({
|
|
410
|
+
key: z.string().trim().min(1).max(64),
|
|
411
|
+
...stageAttributesShape,
|
|
412
|
+
tasks: stageTasksSchema.optional(),
|
|
413
|
+
})
|
|
414
|
+
.strict();
|
|
415
|
+
/**
|
|
416
|
+
* `POST /projects/templates`, `PUT /projects/templates/:id` — the whole
|
|
417
|
+
* Template in one body, saved in one Command. A Template carries structure
|
|
418
|
+
* only: no Organizations, Members, value or links (US3 sc.1).
|
|
419
|
+
*/
|
|
420
|
+
export const ProjectTemplateBodySchema = z
|
|
421
|
+
.object({
|
|
422
|
+
name: z.string().trim().min(1).max(PROJECT_TEMPLATE_NAME_MAX),
|
|
423
|
+
description: descriptionSchema.optional(),
|
|
424
|
+
roleIds: distinctIds(50).optional(),
|
|
425
|
+
stages: z.array(ProjectTemplateStageInputSchema).min(1).max(PROJECT_STAGES_MAX),
|
|
426
|
+
moves: z
|
|
427
|
+
.array(z
|
|
428
|
+
.object({ fromStageKey: z.string().min(1).max(64), toStageKey: z.string().min(1).max(64) })
|
|
429
|
+
.strict())
|
|
430
|
+
.max(PROJECT_STAGES_MAX * PROJECT_STAGES_MAX)
|
|
431
|
+
.optional(),
|
|
432
|
+
})
|
|
433
|
+
.strict()
|
|
434
|
+
.superRefine((body, ctx) => {
|
|
435
|
+
const keys = body.stages.map((stage) => stage.key);
|
|
436
|
+
const known = new Set(keys);
|
|
437
|
+
if (known.size !== keys.length) {
|
|
438
|
+
ctx.addIssue({ code: 'custom', path: ['stages'], message: 'Each Stage key may appear once' });
|
|
439
|
+
}
|
|
440
|
+
const seen = new Set();
|
|
441
|
+
(body.moves ?? []).forEach((move, index) => {
|
|
442
|
+
if (!known.has(move.fromStageKey) || !known.has(move.toStageKey)) {
|
|
443
|
+
ctx.addIssue({ code: 'custom', path: ['moves', index], message: 'A move must name Stages of this Template' });
|
|
444
|
+
}
|
|
445
|
+
if (move.fromStageKey === move.toStageKey) {
|
|
446
|
+
ctx.addIssue({ code: 'custom', path: ['moves', index], message: 'A move must connect two different Stages' });
|
|
447
|
+
}
|
|
448
|
+
const pair = `${move.fromStageKey}\u0000${move.toStageKey}`;
|
|
449
|
+
if (seen.has(pair)) {
|
|
450
|
+
ctx.addIssue({ code: 'custom', path: ['moves', index], message: 'Each move may appear once' });
|
|
451
|
+
}
|
|
452
|
+
seen.add(pair);
|
|
453
|
+
});
|
|
454
|
+
});
|
|
455
|
+
// ---------------------------------------------------------------------------
|
|
456
|
+
// §2.6 Analytics — request
|
|
457
|
+
// ---------------------------------------------------------------------------
|
|
458
|
+
/** Every `GET /projects/analytics/*` figure takes this (`projects:analytics`). */
|
|
459
|
+
export const ProjectAnalyticsQuerySchema = z
|
|
460
|
+
.object({
|
|
461
|
+
from: calendarDateSchema,
|
|
462
|
+
to: calendarDateSchema,
|
|
463
|
+
templateId: uuid.optional(),
|
|
464
|
+
organizationId: uuid.optional(),
|
|
465
|
+
projectManagerId: uuid.optional(),
|
|
466
|
+
})
|
|
467
|
+
.refine((query) => query.from <= query.to, { message: 'The range ends before it starts', path: ['to'] });
|
|
468
|
+
// ---------------------------------------------------------------------------
|
|
469
|
+
// Responses
|
|
470
|
+
// ---------------------------------------------------------------------------
|
|
471
|
+
const personSchema = z.object({ id: uuid, name: z.string() });
|
|
472
|
+
/** A Project Role or a loss reason as configured. */
|
|
473
|
+
const dictionaryEntrySchema = z.object({
|
|
474
|
+
id: uuid,
|
|
475
|
+
code: z.string(),
|
|
476
|
+
name: z.record(z.string(), z.string()),
|
|
477
|
+
defaultName: z.string(),
|
|
478
|
+
/** The name in the language the response is written in (`pickLocalized`, then `defaultName`). */
|
|
479
|
+
label: z.string(),
|
|
480
|
+
/** Seeded rows: renamable and archivable, never deletable. */
|
|
481
|
+
isSystem: z.boolean(),
|
|
482
|
+
archivedAt: isoTimestampSchema.nullable(),
|
|
483
|
+
position: z.number().int(),
|
|
484
|
+
});
|
|
485
|
+
export const ProjectRoleSchema = dictionaryEntrySchema;
|
|
486
|
+
export const ProjectLossReasonSchema = dictionaryEntrySchema;
|
|
487
|
+
export const ProjectCurrentStageSchema = z.object({
|
|
488
|
+
id: uuid,
|
|
489
|
+
name: z.string(),
|
|
490
|
+
color: z.string(),
|
|
491
|
+
deadlineOn: z.string().nullable(),
|
|
492
|
+
overdue: z.boolean(),
|
|
493
|
+
});
|
|
494
|
+
export const ProjectSummarySchema = z.object({
|
|
495
|
+
id: uuid,
|
|
496
|
+
number: z.string(),
|
|
497
|
+
title: z.string(),
|
|
498
|
+
state: projectStateSchema,
|
|
499
|
+
currentStage: ProjectCurrentStageSchema.nullable(),
|
|
500
|
+
organizations: z.array(z.object({ id: uuid, name: z.string() })),
|
|
501
|
+
value: ProjectValueSchema.nullable(),
|
|
502
|
+
projectManagers: z.array(personSchema),
|
|
503
|
+
createdAt: isoTimestampSchema,
|
|
504
|
+
closedAt: isoTimestampSchema.nullable(),
|
|
505
|
+
});
|
|
506
|
+
/** `GET /projects` — one page, its next cursor and the total the caller may see. */
|
|
507
|
+
export const ProjectListResponseSchema = z.object({
|
|
508
|
+
items: z.array(ProjectSummarySchema),
|
|
509
|
+
nextCursor: z.string().nullable(),
|
|
510
|
+
total: z.number().int().nonnegative(),
|
|
511
|
+
});
|
|
512
|
+
export const ProjectStageSchema = z.object({
|
|
513
|
+
id: uuid,
|
|
514
|
+
name: z.string(),
|
|
515
|
+
color: z.string(),
|
|
516
|
+
position: z.number().int(),
|
|
517
|
+
plannedDurationDays: z.number().int(),
|
|
518
|
+
responsibleRoleIds: z.array(uuid),
|
|
519
|
+
alertOffsetsDays: z.array(z.number().int()),
|
|
520
|
+
completionGate: z.boolean(),
|
|
521
|
+
completionPermitted: z.boolean(),
|
|
522
|
+
startedOn: z.string().nullable(),
|
|
523
|
+
deadlineOn: z.string().nullable(),
|
|
524
|
+
deadlineManual: z.boolean(),
|
|
525
|
+
tasksMaterializedAt: isoTimestampSchema.nullable(),
|
|
526
|
+
tasksSkippedAt: isoTimestampSchema.nullable(),
|
|
527
|
+
/**
|
|
528
|
+
* Creating the Stage's Tasks failed on its last entry and has not been done
|
|
529
|
+
* since — `POST …/stages/:stageId/materialize-tasks` creates them (R-8).
|
|
530
|
+
*/
|
|
531
|
+
tasksMaterializeFailed: z.boolean(),
|
|
532
|
+
/** The Stage's own Task definitions (R-7). */
|
|
533
|
+
stageTasks: z.array(StageTaskDefinitionSchema.extend({ id: uuid, position: z.number().int() })),
|
|
534
|
+
});
|
|
535
|
+
export const ProjectMemberSchema = z.object({
|
|
536
|
+
id: uuid,
|
|
537
|
+
adminUser: personSchema.extend({ active: z.boolean() }),
|
|
538
|
+
roles: z.array(z.object({ id: uuid, name: z.string(), archived: z.boolean() })),
|
|
539
|
+
addedAt: isoTimestampSchema,
|
|
540
|
+
});
|
|
541
|
+
export const ProjectDetailSchema = ProjectSummarySchema.extend({
|
|
542
|
+
description: z.string(),
|
|
543
|
+
references: z.array(RecordReferenceSchema),
|
|
544
|
+
startOn: z.string(),
|
|
545
|
+
visibility: projectVisibilitySchema,
|
|
546
|
+
viewers: z.array(personSchema),
|
|
547
|
+
template: z.object({ id: uuid, name: z.string() }).nullable(),
|
|
548
|
+
lostStageId: uuid.nullable(),
|
|
549
|
+
lossReason: z.object({ id: uuid, name: z.string() }).nullable(),
|
|
550
|
+
lossComment: z.string().nullable(),
|
|
551
|
+
stages: z.array(ProjectStageSchema),
|
|
552
|
+
moves: z.array(z.object({ fromStageId: uuid, toStageId: uuid })),
|
|
553
|
+
/** Stages no permitted move reaches from the first — a warning, not an error. */
|
|
554
|
+
unreachableStageIds: z.array(uuid),
|
|
555
|
+
members: z.array(ProjectMemberSchema),
|
|
556
|
+
linkCount: z.number().int().nonnegative(),
|
|
557
|
+
/** Messages written by somebody else since the caller's read marker. */
|
|
558
|
+
unreadMessageCount: z.number().int().nonnegative(),
|
|
559
|
+
customFieldValues: customFieldValuesSchema,
|
|
560
|
+
version: z.number().int().positive(),
|
|
561
|
+
permissions: z.object({ canWrite: z.boolean(), canConfigure: z.boolean() }),
|
|
562
|
+
});
|
|
563
|
+
export const ProjectStageEntrySchema = z.object({
|
|
564
|
+
id: uuid,
|
|
565
|
+
kind: projectStageEntryKindSchema,
|
|
566
|
+
fromStageId: uuid.nullable(),
|
|
567
|
+
toStageId: uuid.nullable(),
|
|
568
|
+
fromStageName: z.string().nullable(),
|
|
569
|
+
toStageName: z.string().nullable(),
|
|
570
|
+
notes: z.array(projectStageEntryNoteSchema),
|
|
571
|
+
actor: personSchema.nullable(),
|
|
572
|
+
at: isoTimestampSchema,
|
|
573
|
+
});
|
|
574
|
+
export const SetProjectMovesResultSchema = z.object({
|
|
575
|
+
moves: z.array(z.object({ fromStageId: uuid, toStageId: uuid })),
|
|
576
|
+
unreachableStageIds: z.array(uuid),
|
|
577
|
+
});
|
|
578
|
+
/** `POST /projects/:id/move` — the Project after the move and what the move recorded. */
|
|
579
|
+
export const ProjectMoveResultSchema = z.object({
|
|
580
|
+
project: ProjectDetailSchema,
|
|
581
|
+
entry: ProjectStageEntrySchema,
|
|
582
|
+
createdTaskIds: z.array(uuid),
|
|
583
|
+
notes: z.array(projectStageEntryNoteSchema),
|
|
584
|
+
});
|
|
585
|
+
export const MaterializeStageTasksResultSchema = z.object({ created: z.number().int().nonnegative() });
|
|
586
|
+
/**
|
|
587
|
+
* A linked record. `number`, `status`, `amount`, `currency` and `href` are
|
|
588
|
+
* present only when `available` — a record the reader may not read, one that is
|
|
589
|
+
* gone, or one whose owning module is switched off is listed as unavailable
|
|
590
|
+
* (FR-023, FR-024).
|
|
591
|
+
*/
|
|
592
|
+
export const ProjectLinkSchema = z.object({
|
|
593
|
+
id: uuid,
|
|
594
|
+
kind: projectRecordKindSchema,
|
|
595
|
+
recordId: uuid,
|
|
596
|
+
available: z.boolean(),
|
|
597
|
+
number: z.string().optional(),
|
|
598
|
+
status: z.string().optional(),
|
|
599
|
+
amount: z.string().optional(),
|
|
600
|
+
currency: z.string().optional(),
|
|
601
|
+
href: z.string().optional(),
|
|
602
|
+
linkedBy: personSchema.nullable(),
|
|
603
|
+
linkedAt: isoTimestampSchema,
|
|
604
|
+
});
|
|
605
|
+
/** `GET /projects/:id/tasks` — Tasks by Stage; `tasksAvailable: false` while `tasks` is off. */
|
|
606
|
+
export const ProjectTasksResponseSchema = z.object({
|
|
607
|
+
tasksAvailable: z.boolean(),
|
|
608
|
+
stages: z.array(z.object({ stageId: uuid, tasks: z.array(TaskSummarySchema) })),
|
|
609
|
+
});
|
|
610
|
+
export const ProjectCommentSchema = z.object({
|
|
611
|
+
id: uuid,
|
|
612
|
+
kind: projectCommentKindSchema,
|
|
613
|
+
author: personSchema,
|
|
614
|
+
body: z.string(),
|
|
615
|
+
references: z.array(RecordReferenceSchema),
|
|
616
|
+
editedAt: isoTimestampSchema.nullable(),
|
|
617
|
+
createdAt: isoTimestampSchema,
|
|
618
|
+
});
|
|
619
|
+
export const ProjectUnreadMessagesSchema = z.object({
|
|
620
|
+
unreadMessageCount: z.number().int().nonnegative(),
|
|
621
|
+
});
|
|
622
|
+
export const ProjectAttachmentSchema = z.object({
|
|
623
|
+
id: uuid,
|
|
624
|
+
assetId: uuid,
|
|
625
|
+
fileName: z.string(),
|
|
626
|
+
mimeType: z.string(),
|
|
627
|
+
sizeBytes: z.number().int().nonnegative(),
|
|
628
|
+
url: z.string().nullable(),
|
|
629
|
+
uploadedBy: personSchema,
|
|
630
|
+
createdAt: isoTimestampSchema,
|
|
631
|
+
});
|
|
632
|
+
export const ProjectMentionableOptionSchema = z.object({ id: uuid, name: z.string(), email: z.string() });
|
|
633
|
+
export const ProjectTemplateSummarySchema = z.object({
|
|
634
|
+
id: uuid,
|
|
635
|
+
name: z.string(),
|
|
636
|
+
stageCount: z.number().int().nonnegative(),
|
|
637
|
+
archivedAt: isoTimestampSchema.nullable(),
|
|
638
|
+
updatedAt: isoTimestampSchema,
|
|
639
|
+
});
|
|
640
|
+
export const ProjectTemplateDetailSchema = z.object({
|
|
641
|
+
id: uuid,
|
|
642
|
+
name: z.string(),
|
|
643
|
+
description: z.string(),
|
|
644
|
+
roleIds: z.array(uuid),
|
|
645
|
+
stages: z.array(z.object({
|
|
646
|
+
id: uuid,
|
|
647
|
+
name: z.string(),
|
|
648
|
+
color: z.string(),
|
|
649
|
+
position: z.number().int(),
|
|
650
|
+
plannedDurationDays: z.number().int(),
|
|
651
|
+
responsibleRoleIds: z.array(uuid),
|
|
652
|
+
alertOffsetsDays: z.array(z.number().int()),
|
|
653
|
+
completionGate: z.boolean(),
|
|
654
|
+
completionPermitted: z.boolean(),
|
|
655
|
+
tasks: z.array(StageTaskDefinitionSchema.extend({ id: uuid, position: z.number().int() })),
|
|
656
|
+
})),
|
|
657
|
+
moves: z.array(z.object({ fromStageId: uuid, toStageId: uuid })),
|
|
658
|
+
archivedAt: isoTimestampSchema.nullable(),
|
|
659
|
+
createdAt: isoTimestampSchema,
|
|
660
|
+
updatedAt: isoTimestampSchema,
|
|
661
|
+
});
|
|
662
|
+
export const ProjectDetailResponseSchema = dataEnvelope(ProjectDetailSchema);
|
|
663
|
+
export const ProjectSummaryResponseSchema = dataEnvelope(ProjectSummarySchema);
|
|
664
|
+
export const ProjectStageResponseSchema = dataEnvelope(ProjectStageSchema);
|
|
665
|
+
export const ProjectStageEntryListResponseSchema = dataEnvelope(z.array(ProjectStageEntrySchema));
|
|
666
|
+
export const SetProjectMovesResponseSchema = dataEnvelope(SetProjectMovesResultSchema);
|
|
667
|
+
export const ProjectMoveResponseSchema = dataEnvelope(ProjectMoveResultSchema);
|
|
668
|
+
export const MaterializeStageTasksResponseSchema = dataEnvelope(MaterializeStageTasksResultSchema);
|
|
669
|
+
export const ProjectLinkResponseSchema = dataEnvelope(ProjectLinkSchema);
|
|
670
|
+
export const ProjectLinkListResponseSchema = dataEnvelope(z.array(ProjectLinkSchema));
|
|
671
|
+
export const ProjectTasksEnvelopeSchema = dataEnvelope(ProjectTasksResponseSchema);
|
|
672
|
+
export const ProjectCommentResponseSchema = dataEnvelope(ProjectCommentSchema);
|
|
673
|
+
export const ProjectCommentListResponseSchema = dataEnvelope(z.array(ProjectCommentSchema));
|
|
674
|
+
export const ProjectUnreadMessagesResponseSchema = dataEnvelope(ProjectUnreadMessagesSchema);
|
|
675
|
+
export const ProjectAttachmentResponseSchema = dataEnvelope(ProjectAttachmentSchema);
|
|
676
|
+
export const ProjectAttachmentListResponseSchema = dataEnvelope(z.array(ProjectAttachmentSchema));
|
|
677
|
+
export const ProjectMentionableLookupResponseSchema = dataEnvelope(z.array(ProjectMentionableOptionSchema));
|
|
678
|
+
export const ProjectOrganizationOptionSchema = z.object({ id: uuid, name: z.string() });
|
|
679
|
+
export const ProjectOrganizationLookupResponseSchema = dataEnvelope(z.array(ProjectOrganizationOptionSchema));
|
|
680
|
+
export const ProjectAdminUserOptionSchema = z.object({ id: uuid, name: z.string(), email: z.string() });
|
|
681
|
+
export const ProjectAdminUserLookupResponseSchema = dataEnvelope(z.array(ProjectAdminUserOptionSchema));
|
|
682
|
+
/**
|
|
683
|
+
* `GET /projects/visibility-setting` — the module setting `projects.visibility`
|
|
684
|
+
* as it stands, so a screen can say what *Follow the module setting* means.
|
|
685
|
+
*/
|
|
686
|
+
export const ProjectVisibilitySettingSchema = z.object({ setting: projectVisibilitySettingSchema });
|
|
687
|
+
export const ProjectVisibilitySettingResponseSchema = dataEnvelope(ProjectVisibilitySettingSchema);
|
|
688
|
+
export const ProjectRoleResponseSchema = dataEnvelope(ProjectRoleSchema);
|
|
689
|
+
export const ProjectRoleListResponseSchema = dataEnvelope(z.array(ProjectRoleSchema));
|
|
690
|
+
export const ProjectLossReasonResponseSchema = dataEnvelope(ProjectLossReasonSchema);
|
|
691
|
+
export const ProjectLossReasonListResponseSchema = dataEnvelope(z.array(ProjectLossReasonSchema));
|
|
692
|
+
export const ProjectTemplateListResponseSchema = dataEnvelope(z.array(ProjectTemplateSummarySchema));
|
|
693
|
+
export const ProjectTemplateResponseSchema = dataEnvelope(ProjectTemplateDetailSchema);
|
|
694
|
+
// `GET /projects/:id/history` answers `RecordHistoryPageSchema`, and
|
|
695
|
+
// `GET /projects/lookups/documents` `RecordDocumentLookupResponseSchema`, both
|
|
696
|
+
// of `record-references.ts`.
|
|
697
|
+
// ---------------------------------------------------------------------------
|
|
698
|
+
// §2.6 Analytics — responses (FR-037, FR-038)
|
|
699
|
+
// ---------------------------------------------------------------------------
|
|
700
|
+
/** An amount in one currency; money figures are per currency, never summed across. */
|
|
701
|
+
export const ProjectCurrencyAmountSchema = z.object({ currency: z.string(), amount: z.string() });
|
|
702
|
+
/**
|
|
703
|
+
* Every figure states the period it covers, how many Projects it was computed
|
|
704
|
+
* from and how many it left out for a missing value (FR-038).
|
|
705
|
+
*/
|
|
706
|
+
export function projectAnalyticsEnvelope(data) {
|
|
707
|
+
return z.object({
|
|
708
|
+
from: z.string(),
|
|
709
|
+
to: z.string(),
|
|
710
|
+
projectCount: z.number().int().nonnegative(),
|
|
711
|
+
excluded: z.object({ noValue: z.number().int().nonnegative() }),
|
|
712
|
+
data,
|
|
713
|
+
});
|
|
714
|
+
}
|
|
715
|
+
export const ProjectAnalyticsSummarySchema = z.object({
|
|
716
|
+
opened: z.number().int().nonnegative(),
|
|
717
|
+
completed: z.number().int().nonnegative(),
|
|
718
|
+
lost: z.number().int().nonnegative(),
|
|
719
|
+
/** completed / (completed + lost); `null` when nothing closed. */
|
|
720
|
+
completionRate: z.number().min(0).max(1).nullable(),
|
|
721
|
+
});
|
|
722
|
+
export const ProjectAnalyticsDurationsSchema = z.object({
|
|
723
|
+
completedAverageDays: z.number().nullable(),
|
|
724
|
+
completedCount: z.number().int().nonnegative(),
|
|
725
|
+
lostAverageDays: z.number().nullable(),
|
|
726
|
+
lostCount: z.number().int().nonnegative(),
|
|
727
|
+
});
|
|
728
|
+
/** Grouped by Stage **name** (`lower(trim(name))`), as Stages are per Project (R-15). */
|
|
729
|
+
export const ProjectAnalyticsTimeInStageSchema = z.array(z.object({
|
|
730
|
+
stageName: z.string(),
|
|
731
|
+
averageDays: z.number().nullable(),
|
|
732
|
+
sampleCount: z.number().int().nonnegative(),
|
|
733
|
+
}));
|
|
734
|
+
export const ProjectAnalyticsLossesSchema = z.object({
|
|
735
|
+
byStage: z.array(z.object({ stageName: z.string(), count: z.number().int().nonnegative(), share: z.number() })),
|
|
736
|
+
byReason: z.array(z.object({
|
|
737
|
+
lossReasonId: uuid,
|
|
738
|
+
code: z.string(),
|
|
739
|
+
name: z.string(),
|
|
740
|
+
count: z.number().int().nonnegative(),
|
|
741
|
+
share: z.number(),
|
|
742
|
+
})),
|
|
743
|
+
lostValue: z.array(ProjectCurrencyAmountSchema),
|
|
744
|
+
});
|
|
745
|
+
export const ProjectAnalyticsValueSchema = z.object({
|
|
746
|
+
average: z.array(ProjectCurrencyAmountSchema.extend({ count: z.number().int().nonnegative() })),
|
|
747
|
+
});
|
|
748
|
+
export const ProjectAnalyticsTopOpenSchema = z.array(ProjectSummarySchema);
|
|
749
|
+
export const ProjectAnalyticsManagersSchema = z.array(z.object({ adminUser: personSchema, completedCount: z.number().int().nonnegative() }));
|
|
750
|
+
export const ProjectAnalyticsSummaryResponseSchema = projectAnalyticsEnvelope(ProjectAnalyticsSummarySchema);
|
|
751
|
+
export const ProjectAnalyticsDurationsResponseSchema = projectAnalyticsEnvelope(ProjectAnalyticsDurationsSchema);
|
|
752
|
+
export const ProjectAnalyticsTimeInStageResponseSchema = projectAnalyticsEnvelope(ProjectAnalyticsTimeInStageSchema);
|
|
753
|
+
export const ProjectAnalyticsLossesResponseSchema = projectAnalyticsEnvelope(ProjectAnalyticsLossesSchema);
|
|
754
|
+
export const ProjectAnalyticsValueResponseSchema = projectAnalyticsEnvelope(ProjectAnalyticsValueSchema);
|
|
755
|
+
export const ProjectAnalyticsTopOpenResponseSchema = projectAnalyticsEnvelope(ProjectAnalyticsTopOpenSchema);
|
|
756
|
+
export const ProjectAnalyticsManagersResponseSchema = projectAnalyticsEnvelope(ProjectAnalyticsManagersSchema);
|
|
757
|
+
// ---------------------------------------------------------------------------
|
|
758
|
+
// Error codes (`contracts/admin-api.md` §2)
|
|
759
|
+
// ---------------------------------------------------------------------------
|
|
760
|
+
/**
|
|
761
|
+
* The codes the Projects API raises. Each joins the platform's `ERROR_CODES`,
|
|
762
|
+
* the `projects` manifest's `errorCodes` and the module's `errors.<CODE>`
|
|
763
|
+
* sentences in the change that adds its first raise site —
|
|
764
|
+
* `check:error-translations` refuses a code enumerated before a manifest
|
|
765
|
+
* declares it.
|
|
766
|
+
*/
|
|
767
|
+
export const PROJECTS_ERROR_CODES = [
|
|
768
|
+
/** No such Project, or one out of the caller's reach or visibility — indistinguishable. */
|
|
769
|
+
'PROJECT_NOT_FOUND',
|
|
770
|
+
/** A Project with links cannot be deleted; unlink first. */
|
|
771
|
+
'PROJECT_HAS_LINKS',
|
|
772
|
+
/** A linked record belongs to the Organization being removed. */
|
|
773
|
+
'PROJECT_ORGANIZATION_IN_USE',
|
|
774
|
+
/** An Organization outside the caller's reach. */
|
|
775
|
+
'PROJECT_ORGANIZATION_OUT_OF_SCOPE',
|
|
776
|
+
'PROJECT_STAGE_CURRENT',
|
|
777
|
+
'PROJECT_STAGE_HAS_TASKS',
|
|
778
|
+
'PROJECT_STAGE_LAST',
|
|
779
|
+
/** The Project's workflow has no move between the two Stages. */
|
|
780
|
+
'PROJECT_MOVE_NOT_PERMITTED',
|
|
781
|
+
/** The Stage's completion gate is closed; `details.openTaskCount` counts the open Tasks, `details.openTasks` names them to a reader of Tasks. */
|
|
782
|
+
'PROJECT_STAGE_GATE_OPEN_TASKS',
|
|
783
|
+
/** The `version` sent is stale. */
|
|
784
|
+
'PROJECT_CHANGED',
|
|
785
|
+
/** A registered stage guard refused; `details.reason` is its sentence. */
|
|
786
|
+
'PROJECT_GUARD_REFUSED',
|
|
787
|
+
/** Completing is not permitted from the current Stage. */
|
|
788
|
+
'PROJECT_COMPLETION_NOT_PERMITTED',
|
|
789
|
+
/** The record to link does not exist or is not readable by the caller. */
|
|
790
|
+
'PROJECT_RECORD_NOT_FOUND',
|
|
791
|
+
/** The record already belongs to a Project; `details.project` names it if visible. */
|
|
792
|
+
'PROJECT_RECORD_ALREADY_LINKED',
|
|
793
|
+
'PROJECT_LINK_ORGANIZATION_MISMATCH',
|
|
794
|
+
/** Only a note's author edits or deletes it. */
|
|
795
|
+
'PROJECT_NOTE_NOT_AUTHOR',
|
|
796
|
+
/** A message is never edited or deleted (FR-025). */
|
|
797
|
+
'PROJECT_MESSAGE_IMMUTABLE',
|
|
798
|
+
/** `materialize-tasks` was asked of a Stage whose entry did not record a failure (R-8). */
|
|
799
|
+
'PROJECT_STAGE_TASKS_NOT_RETRYABLE',
|
|
800
|
+
/** The loss reason is unknown or archived (FR-005). */
|
|
801
|
+
'PROJECT_LOSS_REASON_INVALID',
|
|
802
|
+
/** A Member or listed person is not an active administrator, or a Role is unknown (FR-008). */
|
|
803
|
+
'PROJECT_MEMBER_INVALID',
|
|
804
|
+
/** The Template is unknown or archived. */
|
|
805
|
+
'PROJECT_TEMPLATE_NOT_FOUND',
|
|
806
|
+
/** No Project Role or loss reason with that id. */
|
|
807
|
+
'PROJECT_DICTIONARY_ENTRY_NOT_FOUND',
|
|
808
|
+
/** A seeded Role or loss reason is never deleted — archive it. */
|
|
809
|
+
'PROJECT_DICTIONARY_ENTRY_SYSTEM',
|
|
810
|
+
/** A Project or Template uses the Role or loss reason — archive it. */
|
|
811
|
+
'PROJECT_DICTIONARY_ENTRY_IN_USE',
|
|
812
|
+
/** Another row of the same dictionary has this default name, whatever its case. */
|
|
813
|
+
'PROJECT_DICTIONARY_NAME_TAKEN',
|
|
814
|
+
/** The uploaded file is larger than {@link PROJECT_ATTACHMENT_MAX_BYTES}. */
|
|
815
|
+
'PROJECT_ATTACHMENT_TOO_LARGE',
|
|
816
|
+
];
|
|
817
|
+
/**
|
|
818
|
+
* `details` of 409 `PROJECT_STAGE_GATE_OPEN_TASKS`: how many Tasks of the Stage
|
|
819
|
+
* are open, and — only to a caller who holds `tasks:read` — which ones. A move
|
|
820
|
+
* needs `projects:write` alone, so a Task's number and title are not the
|
|
821
|
+
* refusal's to hand to somebody who may not read Tasks.
|
|
822
|
+
*/
|
|
823
|
+
export const ProjectStageGateOpenTasksDetailsSchema = z.object({
|
|
824
|
+
openTaskCount: z.number().int().positive(),
|
|
825
|
+
openTasks: z.array(z.object({ id: uuid, number: z.string(), title: z.string() })).optional(),
|
|
826
|
+
});
|
|
827
|
+
export const PROJECTS_EVENTS = {
|
|
828
|
+
PROJECT_CREATED: 'projects.project.created.v1',
|
|
829
|
+
STAGE_MOVED: 'projects.stage.moved.v1',
|
|
830
|
+
PROJECT_CLOSED: 'projects.project.closed.v1',
|
|
831
|
+
PROJECT_REOPENED: 'projects.project.reopened.v1',
|
|
832
|
+
RECORD_LINKED: 'projects.record.linked.v1',
|
|
833
|
+
RECORD_UNLINKED: 'projects.record.unlinked.v1',
|
|
834
|
+
};
|
|
835
|
+
/** The most Projects one `ProjectReadPort.search` answers. */
|
|
836
|
+
export const PROJECT_READ_PORT_SEARCH_MAX = 20;
|
|
837
|
+
//# sourceMappingURL=projects.js.map
|