@htilabs/platform-common-models 0.1.0-beta.1 → 0.1.0-beta.3

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.
@@ -0,0 +1,225 @@
1
+ /**
2
+ * @htilabs/platform-common-models — IC-48 Universal Service Catalog
3
+ *
4
+ * Thread Universal Service Categories (IC-48) - the canonical taxonomy for
5
+ * victim services across HTI Labs applications.
6
+ *
7
+ * This catalog defines a hierarchical structure of service categories with:
8
+ * - Unique numeric IDs for each category
9
+ * - Hierarchical codes (e.g., "01-04-01" for Medical)
10
+ * - Parent-child relationships via parentId
11
+ * - Selectability flags for leaf vs branch nodes
12
+ *
13
+ * @see https://github.com/htilabstech/thread2 for the source of truth
14
+ */
15
+
16
+ import catalogData from "./service-catalog.json" with { type: "json" };
17
+
18
+ // ─── Types ───────────────────────────────────────────────────────────
19
+
20
+ export interface IC48CatalogMeta {
21
+ description: string;
22
+ mece: boolean;
23
+ levels: string[];
24
+ }
25
+
26
+ export interface IC48CategoryCrosswalk {
27
+ [key: string]: unknown;
28
+ }
29
+
30
+ export interface IC48Category {
31
+ /** Unique numeric identifier for this category */
32
+ id: number;
33
+ /** Hierarchical code (e.g., "01-04-01") */
34
+ code: string;
35
+ /** Display label */
36
+ label: string;
37
+ /** Full description of the service category */
38
+ description: string;
39
+ /** Hierarchy level (0=root, 1=topic, 2=primary, etc.) */
40
+ level: number;
41
+ /** Parent category ID, null for root/topic-level */
42
+ parentId: number | null;
43
+ /** Topic code prefix (e.g., "01-04") */
44
+ topicCode: string;
45
+ /** Sort order within parent */
46
+ sortOrder: number;
47
+ /** Whether this category can be selected (leaf nodes typically true) */
48
+ isSelectable: boolean;
49
+ /** Cross-reference mappings to other taxonomies */
50
+ crosswalk: IC48CategoryCrosswalk;
51
+ }
52
+
53
+ export interface IC48Catalog {
54
+ catalogVersion: string;
55
+ catalogDate: string;
56
+ meta: IC48CatalogMeta;
57
+ categories: IC48Category[];
58
+ }
59
+
60
+ // ─── Catalog Data ────────────────────────────────────────────────────
61
+
62
+ /** The full IC-48 service catalog */
63
+ export const IC_48_SERVICE_CATALOG = catalogData as IC48Catalog;
64
+
65
+ /** All service categories as an array */
66
+ export const IC_48_CATEGORIES = IC_48_SERVICE_CATALOG.categories;
67
+
68
+ // ─── Lookup Maps (built once at module load) ─────────────────────────
69
+
70
+ /** Map of category ID to category object for O(1) lookup */
71
+ export const IC_48_BY_ID: ReadonlyMap<number, IC48Category> = new Map(
72
+ IC_48_CATEGORIES.map((cat) => [cat.id, cat])
73
+ );
74
+
75
+ /** Map of category code to category object for O(1) lookup */
76
+ export const IC_48_BY_CODE: ReadonlyMap<string, IC48Category> = new Map(
77
+ IC_48_CATEGORIES.map((cat) => [cat.code, cat])
78
+ );
79
+
80
+ // ─── Helper Functions ────────────────────────────────────────────────
81
+
82
+ /**
83
+ * Get a service category by its numeric ID.
84
+ * @param id - The category ID
85
+ * @returns The category or undefined if not found
86
+ */
87
+ export function getIC48CategoryById(id: number): IC48Category | undefined {
88
+ return IC_48_BY_ID.get(id);
89
+ }
90
+
91
+ /**
92
+ * Get a service category by its hierarchical code.
93
+ * @param code - The category code (e.g., "01-04-01")
94
+ * @returns The category or undefined if not found
95
+ */
96
+ export function getIC48CategoryByCode(code: string): IC48Category | undefined {
97
+ return IC_48_BY_CODE.get(code);
98
+ }
99
+
100
+ /**
101
+ * Get the label for a service category by ID.
102
+ * @param id - The category ID
103
+ * @returns The label or "Unknown Service" if not found
104
+ */
105
+ export function getIC48Label(id: number): string {
106
+ return IC_48_BY_ID.get(id)?.label ?? "Unknown Service";
107
+ }
108
+
109
+ /**
110
+ * Get all children of a category (direct descendants only).
111
+ * @param parentId - The parent category ID
112
+ * @returns Array of child categories
113
+ */
114
+ export function getIC48ChildCategories(parentId: number): IC48Category[] {
115
+ return IC_48_CATEGORIES.filter((cat) => cat.parentId === parentId);
116
+ }
117
+
118
+ /**
119
+ * Get all selectable (leaf) categories.
120
+ * @returns Array of selectable categories
121
+ */
122
+ export function getIC48SelectableCategories(): IC48Category[] {
123
+ return IC_48_CATEGORIES.filter((cat) => cat.isSelectable);
124
+ }
125
+
126
+ /**
127
+ * Get the root/topic categories (level 1, no parent).
128
+ * @returns Array of topic-level categories
129
+ */
130
+ export function getIC48TopicCategories(): IC48Category[] {
131
+ return IC_48_CATEGORIES.filter((cat) => cat.level === 1 && cat.parentId === null);
132
+ }
133
+
134
+ /**
135
+ * Get the parent category for a given category.
136
+ * @param id - The category ID
137
+ * @returns The parent category or undefined if none/not found
138
+ */
139
+ export function getIC48ParentCategory(id: number): IC48Category | undefined {
140
+ const cat = IC_48_BY_ID.get(id);
141
+ if (!cat || cat.parentId === null) return undefined;
142
+ return IC_48_BY_ID.get(cat.parentId);
143
+ }
144
+
145
+ /**
146
+ * Get all ancestor categories (parent, grandparent, etc.) for a category.
147
+ * @param id - The category ID
148
+ * @returns Array of ancestor categories from immediate parent to root
149
+ */
150
+ export function getIC48AncestorCategories(id: number): IC48Category[] {
151
+ const ancestors: IC48Category[] = [];
152
+ let current = IC_48_BY_ID.get(id);
153
+
154
+ while (current && current.parentId !== null) {
155
+ const parent = IC_48_BY_ID.get(current.parentId);
156
+ if (parent) {
157
+ ancestors.push(parent);
158
+ current = parent;
159
+ } else {
160
+ break;
161
+ }
162
+ }
163
+
164
+ return ancestors;
165
+ }
166
+
167
+ /**
168
+ * Get the topic (level 1) category for any category in the tree.
169
+ * @param id - The category ID
170
+ * @returns The topic-level ancestor or undefined
171
+ */
172
+ export function getIC48TopicForCategory(id: number): IC48Category | undefined {
173
+ const cat = IC_48_BY_ID.get(id);
174
+ if (!cat) return undefined;
175
+ if (cat.level === 1) return cat;
176
+
177
+ const ancestors = getIC48AncestorCategories(id);
178
+ return ancestors.find((a) => a.level === 1);
179
+ }
180
+
181
+ // ─── Well-Known Service IDs ──────────────────────────────────────────
182
+ // These are commonly used service IDs for crisis services and derivation.
183
+
184
+ export const IC_48_CRISIS_SERVICES = {
185
+ /** Interpreter Services (01-07-06) */
186
+ INTERPRETER: 158,
187
+ /** Emergency Transportation (01-09-01) */
188
+ TRANSPORTATION: 28,
189
+ /** Medical Care (01-04-01) */
190
+ MEDICAL: 50,
191
+ /** Emergency Shelter (01-05-01) */
192
+ EMERGENCY_SHELTER: 99,
193
+ } as const;
194
+
195
+ export const IC_48_DERIVATION_SERVICES = {
196
+ /** Advocacy services */
197
+ ADVOCACY: 20,
198
+ /** Child Care */
199
+ CHILD_CARE: 24,
200
+ /** Formal Education */
201
+ FORMAL_EDUCATION: 29,
202
+ /** Safety Planning */
203
+ SAFETY_PLANNING: 37,
204
+ /** Medical Care */
205
+ MEDICAL: 50,
206
+ /** Mental Health */
207
+ MENTAL_HEALTH: 52,
208
+ /** Employment Support */
209
+ EMPLOYMENT: 72,
210
+ /** Case Management */
211
+ CASE_MANAGEMENT: 87,
212
+ /** Emergency Shelter */
213
+ EMERGENCY_SHELTER: 99,
214
+ /** Immigration Relief */
215
+ IMMIGRATION: 113,
216
+ /** Criminal Justice Support */
217
+ CRIMINAL_JUSTICE: 122,
218
+ /** Emergency Safety Assistance */
219
+ EMERGENCY_SAFETY: 124,
220
+ /** Interpreter Services */
221
+ INTERPRETER: 158,
222
+ } as const;
223
+
224
+ export type IC48CrisisServiceId = (typeof IC_48_CRISIS_SERVICES)[keyof typeof IC_48_CRISIS_SERVICES];
225
+ export type IC48DerivationServiceId = (typeof IC_48_DERIVATION_SERVICES)[keyof typeof IC_48_DERIVATION_SERVICES];