hazo_auth 10.23.3 → 10.24.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/README.md CHANGED
@@ -2,6 +2,14 @@
2
2
 
3
3
  A reusable authentication UI component package powered by Next.js, TailwindCSS, and shadcn. It integrates `hazo_config` for configuration management and `hazo_connect` for data access, enabling future components to stay aligned with platform conventions.
4
4
 
5
+ ### What's New in v10.24.0
6
+
7
+ - **Groups + join codes** (ADR-0005) — new `hazo_groups` table (a named collection within a scope,
8
+ e.g. a class) and `hazo_group_memberships` table, migration `024_groups_and_join_codes.sql`.
9
+ `group_service.ts` exports `create_group()` (generates a unique 6-character join code, excluding
10
+ ambiguous characters 0/O, 1/I/l), `join_by_code()` (case-insensitive, idempotent, reactivates a
11
+ previously-removed membership), `get_members()` (paginated), and `get_user_groups()`.
12
+
5
13
  ### What's New in v10.22.0
6
14
 
7
15
  - **Signup lifecycle hooks** — `register_auth_hooks({ on_user_created })` (from `hazo_auth/server-lib`) lets your app react to new-user creation (welcome emails, lifecycle sequences, analytics) without hazo_auth depending on your code. Fires best-effort on email registration, Google/Facebook OAuth, and OTP auto-register, passing `{ user_id, email, name?, auth_provider }`. See [Phase 8.2 of SETUP_CHECKLIST.md](SETUP_CHECKLIST.md#phase-82-signup-lifecycle-hooks-setup-optional).
@@ -0,0 +1,380 @@
1
+ // file_description: service for groups (named collections within a scope, e.g. a
2
+ // class) and join-code based self-service membership, using hazo_connect
3
+ // section: imports
4
+ import type { HazoConnectAdapter } from "hazo_connect";
5
+ import { createCrudService } from "hazo_connect/server";
6
+ import { randomInt } from "crypto";
7
+ import { create_app_logger } from "../app_logger.js";
8
+ import { sanitize_error_for_user } from "../utils/error_sanitizer.js";
9
+ import { get_scope_by_id } from "./scope_service.js";
10
+
11
+ // section: constants
12
+
13
+ /**
14
+ * CRUD service options for hazo_group_memberships table
15
+ * This table uses a composite primary key (user_id, group_id) and no 'id' column
16
+ */
17
+ const GROUP_MEMBERSHIPS_CRUD_OPTIONS = {
18
+ primaryKeys: ["user_id", "group_id"],
19
+ autoId: false as const,
20
+ };
21
+
22
+ // Uppercase alphanumeric, excluding ambiguous characters (0/O, 1/I/l).
23
+ const JOIN_CODE_ALPHABET = "23456789ABCDEFGHJKLMNPQRSTUVWXYZ";
24
+ const JOIN_CODE_LENGTH = 6;
25
+ const MAX_JOIN_CODE_ATTEMPTS = 10;
26
+ const DEFAULT_MEMBERS_PAGE_SIZE = 50;
27
+
28
+ // section: types
29
+
30
+ export type GroupStatus = "ACTIVE" | "ARCHIVED";
31
+ export type GroupMembershipStatus = "ACTIVE" | "REMOVED";
32
+
33
+ export type GroupRecord = {
34
+ id: string;
35
+ scope_id: string;
36
+ name: string;
37
+ join_code: string;
38
+ created_by: string | null;
39
+ metadata: Record<string, unknown> | null;
40
+ status: GroupStatus;
41
+ created_at: string;
42
+ changed_at: string;
43
+ };
44
+
45
+ export type GroupMembershipRecord = {
46
+ user_id: string;
47
+ group_id: string;
48
+ role_id: string | null;
49
+ joined_at: string;
50
+ status: GroupMembershipStatus;
51
+ };
52
+
53
+ export type GroupServiceResult = {
54
+ success: boolean;
55
+ group?: GroupRecord;
56
+ groups?: GroupRecord[];
57
+ membership?: GroupMembershipRecord;
58
+ members?: GroupMembershipRecord[];
59
+ total?: number;
60
+ error?: string;
61
+ };
62
+
63
+ export type CreateGroupData = {
64
+ scope_id: string;
65
+ name: string;
66
+ created_by?: string;
67
+ metadata?: Record<string, unknown>;
68
+ };
69
+
70
+ export type JoinByCodeData = {
71
+ user_id: string;
72
+ join_code: string;
73
+ role_id?: string;
74
+ };
75
+
76
+ export type GetMembersOptions = {
77
+ limit?: number;
78
+ offset?: number;
79
+ };
80
+
81
+ // section: helpers
82
+
83
+ /**
84
+ * Generates a 6-character join code from JOIN_CODE_ALPHABET.
85
+ * Excludes 0/O, 1/I/l so codes are easy to read aloud and transcribe.
86
+ */
87
+ function generate_join_code(): string {
88
+ let code = "";
89
+ for (let i = 0; i < JOIN_CODE_LENGTH; i++) {
90
+ code += JOIN_CODE_ALPHABET[randomInt(JOIN_CODE_ALPHABET.length)];
91
+ }
92
+ return code;
93
+ }
94
+
95
+ /** Parses the metadata TEXT column back into an object, defaulting to null on bad JSON. */
96
+ function parse_metadata(raw: unknown): Record<string, unknown> | null {
97
+ if (typeof raw !== "string" || raw.length === 0) return null;
98
+ try {
99
+ return JSON.parse(raw);
100
+ } catch {
101
+ return null;
102
+ }
103
+ }
104
+
105
+ function to_group_record(row: Record<string, unknown>): GroupRecord {
106
+ return {
107
+ ...(row as unknown as GroupRecord),
108
+ metadata: parse_metadata(row.metadata),
109
+ };
110
+ }
111
+
112
+ // section: main_service
113
+
114
+ /**
115
+ * Creates a new group within a scope, generating a unique join code.
116
+ * Uniqueness is checked proactively (and enforced at the DB level by a
117
+ * UNIQUE constraint on hazo_groups.join_code).
118
+ */
119
+ export async function create_group(
120
+ adapter: HazoConnectAdapter,
121
+ data: CreateGroupData,
122
+ ): Promise<GroupServiceResult> {
123
+ try {
124
+ const group_service = createCrudService(adapter, "hazo_groups");
125
+ const now = new Date().toISOString();
126
+
127
+ const scope_result = await get_scope_by_id(adapter, data.scope_id);
128
+ if (!scope_result.success) {
129
+ return { success: false, error: "Scope not found" };
130
+ }
131
+
132
+ // Proactively avoid known collisions, then insert. If a race slips a
133
+ // duplicate past the proactive check, the DB's UNIQUE constraint on
134
+ // join_code rejects the insert and we regenerate and retry — the
135
+ // proactive check alone can't close that race.
136
+ let last_error: unknown;
137
+ for (let attempt = 0; attempt < MAX_JOIN_CODE_ATTEMPTS; attempt++) {
138
+ const candidate = generate_join_code();
139
+ const existing = await group_service.findBy({ join_code: candidate });
140
+ if (Array.isArray(existing) && existing.length > 0) {
141
+ continue;
142
+ }
143
+
144
+ try {
145
+ const inserted = await group_service.insert({
146
+ scope_id: data.scope_id,
147
+ name: data.name,
148
+ join_code: candidate,
149
+ created_by: data.created_by ?? null,
150
+ metadata: data.metadata ? JSON.stringify(data.metadata) : null,
151
+ status: "ACTIVE",
152
+ created_at: now,
153
+ changed_at: now,
154
+ });
155
+
156
+ if (!Array.isArray(inserted) || inserted.length === 0) {
157
+ return { success: false, error: "Failed to create group" };
158
+ }
159
+
160
+ return { success: true, group: to_group_record(inserted[0]) };
161
+ } catch (insert_error) {
162
+ const message = insert_error instanceof Error ? insert_error.message : String(insert_error);
163
+ if (!/unique/i.test(message)) {
164
+ throw insert_error;
165
+ }
166
+ // join_code collided at the DB level (race with another create_group
167
+ // call) — regenerate and retry.
168
+ last_error = insert_error;
169
+ }
170
+ }
171
+
172
+ throw last_error ?? new Error("Failed to generate a unique join code");
173
+ } catch (error) {
174
+ const logger = create_app_logger();
175
+ const error_message = sanitize_error_for_user(error, {
176
+ logToConsole: true,
177
+ logToLogger: true,
178
+ logger,
179
+ context: {
180
+ filename: "group_service.ts",
181
+ line_number: 0,
182
+ operation: "create_group",
183
+ scope_id: data.scope_id,
184
+ },
185
+ });
186
+ return { success: false, error: error_message };
187
+ }
188
+ }
189
+
190
+ /**
191
+ * Joins a user to a group by join code. Idempotent: an existing ACTIVE
192
+ * membership is returned as-is rather than erroring; a previously REMOVED
193
+ * membership is reactivated.
194
+ */
195
+ export async function join_by_code(
196
+ adapter: HazoConnectAdapter,
197
+ data: JoinByCodeData,
198
+ ): Promise<GroupServiceResult> {
199
+ try {
200
+ const group_service = createCrudService(adapter, "hazo_groups");
201
+ const membership_service = createCrudService(
202
+ adapter,
203
+ "hazo_group_memberships",
204
+ GROUP_MEMBERSHIPS_CRUD_OPTIONS,
205
+ );
206
+ const now = new Date().toISOString();
207
+
208
+ const normalized_code = data.join_code.trim().toUpperCase();
209
+ const groups = await group_service.findBy({ join_code: normalized_code });
210
+ if (!Array.isArray(groups) || groups.length === 0) {
211
+ return { success: false, error: "Invalid join code" };
212
+ }
213
+
214
+ const group = to_group_record(groups[0]);
215
+ if (group.status !== "ACTIVE") {
216
+ return { success: false, error: "This group is no longer accepting members" };
217
+ }
218
+
219
+ const existing = await membership_service.findBy({
220
+ user_id: data.user_id,
221
+ group_id: group.id,
222
+ });
223
+
224
+ if (Array.isArray(existing) && existing.length > 0) {
225
+ const existing_membership = existing[0] as GroupMembershipRecord;
226
+ if (existing_membership.status === "ACTIVE") {
227
+ return { success: true, group, membership: existing_membership };
228
+ }
229
+
230
+ // Reactivate a previously-removed membership.
231
+ const reactivated = await membership_service.upsert(
232
+ {
233
+ user_id: data.user_id,
234
+ group_id: group.id,
235
+ role_id: data.role_id ?? existing_membership.role_id ?? null,
236
+ joined_at: now,
237
+ status: "ACTIVE",
238
+ },
239
+ ["user_id", "group_id"],
240
+ );
241
+
242
+ return {
243
+ success: true,
244
+ group,
245
+ membership: reactivated[0] as GroupMembershipRecord,
246
+ };
247
+ }
248
+
249
+ const inserted = await membership_service.insert({
250
+ user_id: data.user_id,
251
+ group_id: group.id,
252
+ role_id: data.role_id ?? null,
253
+ joined_at: now,
254
+ status: "ACTIVE",
255
+ });
256
+
257
+ if (!Array.isArray(inserted) || inserted.length === 0) {
258
+ return { success: false, error: "Failed to join group" };
259
+ }
260
+
261
+ return { success: true, group, membership: inserted[0] as GroupMembershipRecord };
262
+ } catch (error) {
263
+ const logger = create_app_logger();
264
+ const error_message = sanitize_error_for_user(error, {
265
+ logToConsole: true,
266
+ logToLogger: true,
267
+ logger,
268
+ context: {
269
+ filename: "group_service.ts",
270
+ line_number: 0,
271
+ operation: "join_by_code",
272
+ user_id: data.user_id,
273
+ },
274
+ });
275
+ return { success: false, error: error_message };
276
+ }
277
+ }
278
+
279
+ /**
280
+ * Gets a paginated page of a group's active members.
281
+ */
282
+ export async function get_members(
283
+ adapter: HazoConnectAdapter,
284
+ group_id: string,
285
+ options: GetMembersOptions = {},
286
+ ): Promise<GroupServiceResult> {
287
+ try {
288
+ const membership_service = createCrudService(
289
+ adapter,
290
+ "hazo_group_memberships",
291
+ GROUP_MEMBERSHIPS_CRUD_OPTIONS,
292
+ );
293
+ const limit = options.limit ?? DEFAULT_MEMBERS_PAGE_SIZE;
294
+ const offset = options.offset ?? 0;
295
+
296
+ const members = await membership_service.list((qb) =>
297
+ qb
298
+ .where("group_id", "eq", group_id)
299
+ .where("status", "eq", "ACTIVE")
300
+ .order("joined_at", "asc")
301
+ .limit(limit)
302
+ .offset(offset),
303
+ );
304
+
305
+ const total = await membership_service.findBy({
306
+ group_id,
307
+ status: "ACTIVE",
308
+ });
309
+
310
+ return {
311
+ success: true,
312
+ members: members as GroupMembershipRecord[],
313
+ total: Array.isArray(total) ? total.length : 0,
314
+ };
315
+ } catch (error) {
316
+ const logger = create_app_logger();
317
+ const error_message = sanitize_error_for_user(error, {
318
+ logToConsole: true,
319
+ logToLogger: true,
320
+ logger,
321
+ context: {
322
+ filename: "group_service.ts",
323
+ line_number: 0,
324
+ operation: "get_members",
325
+ group_id,
326
+ },
327
+ });
328
+ return { success: false, error: error_message };
329
+ }
330
+ }
331
+
332
+ /**
333
+ * Gets every group a user has an active membership in.
334
+ */
335
+ export async function get_user_groups(
336
+ adapter: HazoConnectAdapter,
337
+ user_id: string,
338
+ ): Promise<GroupServiceResult> {
339
+ try {
340
+ const membership_service = createCrudService(
341
+ adapter,
342
+ "hazo_group_memberships",
343
+ GROUP_MEMBERSHIPS_CRUD_OPTIONS,
344
+ );
345
+ const group_service = createCrudService(adapter, "hazo_groups");
346
+
347
+ const memberships = await membership_service.findBy({
348
+ user_id,
349
+ status: "ACTIVE",
350
+ });
351
+
352
+ if (!Array.isArray(memberships) || memberships.length === 0) {
353
+ return { success: true, groups: [] };
354
+ }
355
+
356
+ const groups: GroupRecord[] = [];
357
+ for (const membership of memberships as GroupMembershipRecord[]) {
358
+ const found = await group_service.findBy({ id: membership.group_id });
359
+ if (Array.isArray(found) && found.length > 0) {
360
+ groups.push(to_group_record(found[0]));
361
+ }
362
+ }
363
+
364
+ return { success: true, groups };
365
+ } catch (error) {
366
+ const logger = create_app_logger();
367
+ const error_message = sanitize_error_for_user(error, {
368
+ logToConsole: true,
369
+ logToLogger: true,
370
+ logger,
371
+ context: {
372
+ filename: "group_service.ts",
373
+ line_number: 0,
374
+ operation: "get_user_groups",
375
+ user_id,
376
+ },
377
+ });
378
+ return { success: false, error: error_message };
379
+ }
380
+ }
@@ -18,6 +18,7 @@ export * from "./firm_service.js";
18
18
  export * from "./post_verification_service.js";
19
19
  export * from "./scope_service.js";
20
20
  export * from "./user_scope_service.js";
21
+ export * from "./group_service.js";
21
22
  export * from "./oauth_service.js";
22
23
  export * from "./branding_service.js";
23
24
  export * from "./google_token_service.js";
@@ -1,7 +1,7 @@
1
1
  import * as React from "react";
2
2
  import { type VariantProps } from "class-variance-authority";
3
3
  declare const buttonVariants: (props?: ({
4
- variant?: "default" | "link" | "destructive" | "outline" | "secondary" | "ghost" | null | undefined;
4
+ variant?: "link" | "default" | "destructive" | "outline" | "secondary" | "ghost" | null | undefined;
5
5
  size?: "default" | "sm" | "lg" | "icon" | null | undefined;
6
6
  } & import("class-variance-authority/types").ClassProp) | undefined) => string;
7
7
  export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
@@ -0,0 +1,66 @@
1
+ import type { HazoConnectAdapter } from "hazo_connect";
2
+ export type GroupStatus = "ACTIVE" | "ARCHIVED";
3
+ export type GroupMembershipStatus = "ACTIVE" | "REMOVED";
4
+ export type GroupRecord = {
5
+ id: string;
6
+ scope_id: string;
7
+ name: string;
8
+ join_code: string;
9
+ created_by: string | null;
10
+ metadata: Record<string, unknown> | null;
11
+ status: GroupStatus;
12
+ created_at: string;
13
+ changed_at: string;
14
+ };
15
+ export type GroupMembershipRecord = {
16
+ user_id: string;
17
+ group_id: string;
18
+ role_id: string | null;
19
+ joined_at: string;
20
+ status: GroupMembershipStatus;
21
+ };
22
+ export type GroupServiceResult = {
23
+ success: boolean;
24
+ group?: GroupRecord;
25
+ groups?: GroupRecord[];
26
+ membership?: GroupMembershipRecord;
27
+ members?: GroupMembershipRecord[];
28
+ total?: number;
29
+ error?: string;
30
+ };
31
+ export type CreateGroupData = {
32
+ scope_id: string;
33
+ name: string;
34
+ created_by?: string;
35
+ metadata?: Record<string, unknown>;
36
+ };
37
+ export type JoinByCodeData = {
38
+ user_id: string;
39
+ join_code: string;
40
+ role_id?: string;
41
+ };
42
+ export type GetMembersOptions = {
43
+ limit?: number;
44
+ offset?: number;
45
+ };
46
+ /**
47
+ * Creates a new group within a scope, generating a unique join code.
48
+ * Uniqueness is checked proactively (and enforced at the DB level by a
49
+ * UNIQUE constraint on hazo_groups.join_code).
50
+ */
51
+ export declare function create_group(adapter: HazoConnectAdapter, data: CreateGroupData): Promise<GroupServiceResult>;
52
+ /**
53
+ * Joins a user to a group by join code. Idempotent: an existing ACTIVE
54
+ * membership is returned as-is rather than erroring; a previously REMOVED
55
+ * membership is reactivated.
56
+ */
57
+ export declare function join_by_code(adapter: HazoConnectAdapter, data: JoinByCodeData): Promise<GroupServiceResult>;
58
+ /**
59
+ * Gets a paginated page of a group's active members.
60
+ */
61
+ export declare function get_members(adapter: HazoConnectAdapter, group_id: string, options?: GetMembersOptions): Promise<GroupServiceResult>;
62
+ /**
63
+ * Gets every group a user has an active membership in.
64
+ */
65
+ export declare function get_user_groups(adapter: HazoConnectAdapter, user_id: string): Promise<GroupServiceResult>;
66
+ //# sourceMappingURL=group_service.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"group_service.d.ts","sourceRoot":"","sources":["../../../src/lib/services/group_service.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AA0BvD,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,UAAU,CAAC;AAChD,MAAM,MAAM,qBAAqB,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEzD,MAAM,MAAM,WAAW,GAAG;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACzC,MAAM,EAAE,WAAW,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,qBAAqB,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;IACvB,UAAU,CAAC,EAAE,qBAAqB,CAAC;IACnC,OAAO,CAAC,EAAE,qBAAqB,EAAE,CAAC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAmCF;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,kBAAkB,EAC3B,IAAI,EAAE,eAAe,GACpB,OAAO,CAAC,kBAAkB,CAAC,CAkE7B;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,kBAAkB,EAC3B,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,kBAAkB,CAAC,CA+E7B;AAED;;GAEG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,kBAAkB,EAC3B,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,kBAAkB,CAAC,CA4C7B;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,kBAAkB,CAAC,CA0C7B"}
@@ -0,0 +1,266 @@
1
+ import { createCrudService } from "hazo_connect/server";
2
+ import { randomInt } from "crypto";
3
+ import { create_app_logger } from "../app_logger.js";
4
+ import { sanitize_error_for_user } from "../utils/error_sanitizer.js";
5
+ import { get_scope_by_id } from "./scope_service.js";
6
+ // section: constants
7
+ /**
8
+ * CRUD service options for hazo_group_memberships table
9
+ * This table uses a composite primary key (user_id, group_id) and no 'id' column
10
+ */
11
+ const GROUP_MEMBERSHIPS_CRUD_OPTIONS = {
12
+ primaryKeys: ["user_id", "group_id"],
13
+ autoId: false,
14
+ };
15
+ // Uppercase alphanumeric, excluding ambiguous characters (0/O, 1/I/l).
16
+ const JOIN_CODE_ALPHABET = "23456789ABCDEFGHJKLMNPQRSTUVWXYZ";
17
+ const JOIN_CODE_LENGTH = 6;
18
+ const MAX_JOIN_CODE_ATTEMPTS = 10;
19
+ const DEFAULT_MEMBERS_PAGE_SIZE = 50;
20
+ // section: helpers
21
+ /**
22
+ * Generates a 6-character join code from JOIN_CODE_ALPHABET.
23
+ * Excludes 0/O, 1/I/l so codes are easy to read aloud and transcribe.
24
+ */
25
+ function generate_join_code() {
26
+ let code = "";
27
+ for (let i = 0; i < JOIN_CODE_LENGTH; i++) {
28
+ code += JOIN_CODE_ALPHABET[randomInt(JOIN_CODE_ALPHABET.length)];
29
+ }
30
+ return code;
31
+ }
32
+ /** Parses the metadata TEXT column back into an object, defaulting to null on bad JSON. */
33
+ function parse_metadata(raw) {
34
+ if (typeof raw !== "string" || raw.length === 0)
35
+ return null;
36
+ try {
37
+ return JSON.parse(raw);
38
+ }
39
+ catch (_a) {
40
+ return null;
41
+ }
42
+ }
43
+ function to_group_record(row) {
44
+ return Object.assign(Object.assign({}, row), { metadata: parse_metadata(row.metadata) });
45
+ }
46
+ // section: main_service
47
+ /**
48
+ * Creates a new group within a scope, generating a unique join code.
49
+ * Uniqueness is checked proactively (and enforced at the DB level by a
50
+ * UNIQUE constraint on hazo_groups.join_code).
51
+ */
52
+ export async function create_group(adapter, data) {
53
+ var _a;
54
+ try {
55
+ const group_service = createCrudService(adapter, "hazo_groups");
56
+ const now = new Date().toISOString();
57
+ const scope_result = await get_scope_by_id(adapter, data.scope_id);
58
+ if (!scope_result.success) {
59
+ return { success: false, error: "Scope not found" };
60
+ }
61
+ // Proactively avoid known collisions, then insert. If a race slips a
62
+ // duplicate past the proactive check, the DB's UNIQUE constraint on
63
+ // join_code rejects the insert and we regenerate and retry — the
64
+ // proactive check alone can't close that race.
65
+ let last_error;
66
+ for (let attempt = 0; attempt < MAX_JOIN_CODE_ATTEMPTS; attempt++) {
67
+ const candidate = generate_join_code();
68
+ const existing = await group_service.findBy({ join_code: candidate });
69
+ if (Array.isArray(existing) && existing.length > 0) {
70
+ continue;
71
+ }
72
+ try {
73
+ const inserted = await group_service.insert({
74
+ scope_id: data.scope_id,
75
+ name: data.name,
76
+ join_code: candidate,
77
+ created_by: (_a = data.created_by) !== null && _a !== void 0 ? _a : null,
78
+ metadata: data.metadata ? JSON.stringify(data.metadata) : null,
79
+ status: "ACTIVE",
80
+ created_at: now,
81
+ changed_at: now,
82
+ });
83
+ if (!Array.isArray(inserted) || inserted.length === 0) {
84
+ return { success: false, error: "Failed to create group" };
85
+ }
86
+ return { success: true, group: to_group_record(inserted[0]) };
87
+ }
88
+ catch (insert_error) {
89
+ const message = insert_error instanceof Error ? insert_error.message : String(insert_error);
90
+ if (!/unique/i.test(message)) {
91
+ throw insert_error;
92
+ }
93
+ // join_code collided at the DB level (race with another create_group
94
+ // call) — regenerate and retry.
95
+ last_error = insert_error;
96
+ }
97
+ }
98
+ throw last_error !== null && last_error !== void 0 ? last_error : new Error("Failed to generate a unique join code");
99
+ }
100
+ catch (error) {
101
+ const logger = create_app_logger();
102
+ const error_message = sanitize_error_for_user(error, {
103
+ logToConsole: true,
104
+ logToLogger: true,
105
+ logger,
106
+ context: {
107
+ filename: "group_service.ts",
108
+ line_number: 0,
109
+ operation: "create_group",
110
+ scope_id: data.scope_id,
111
+ },
112
+ });
113
+ return { success: false, error: error_message };
114
+ }
115
+ }
116
+ /**
117
+ * Joins a user to a group by join code. Idempotent: an existing ACTIVE
118
+ * membership is returned as-is rather than erroring; a previously REMOVED
119
+ * membership is reactivated.
120
+ */
121
+ export async function join_by_code(adapter, data) {
122
+ var _a, _b, _c;
123
+ try {
124
+ const group_service = createCrudService(adapter, "hazo_groups");
125
+ const membership_service = createCrudService(adapter, "hazo_group_memberships", GROUP_MEMBERSHIPS_CRUD_OPTIONS);
126
+ const now = new Date().toISOString();
127
+ const normalized_code = data.join_code.trim().toUpperCase();
128
+ const groups = await group_service.findBy({ join_code: normalized_code });
129
+ if (!Array.isArray(groups) || groups.length === 0) {
130
+ return { success: false, error: "Invalid join code" };
131
+ }
132
+ const group = to_group_record(groups[0]);
133
+ if (group.status !== "ACTIVE") {
134
+ return { success: false, error: "This group is no longer accepting members" };
135
+ }
136
+ const existing = await membership_service.findBy({
137
+ user_id: data.user_id,
138
+ group_id: group.id,
139
+ });
140
+ if (Array.isArray(existing) && existing.length > 0) {
141
+ const existing_membership = existing[0];
142
+ if (existing_membership.status === "ACTIVE") {
143
+ return { success: true, group, membership: existing_membership };
144
+ }
145
+ // Reactivate a previously-removed membership.
146
+ const reactivated = await membership_service.upsert({
147
+ user_id: data.user_id,
148
+ group_id: group.id,
149
+ role_id: (_b = (_a = data.role_id) !== null && _a !== void 0 ? _a : existing_membership.role_id) !== null && _b !== void 0 ? _b : null,
150
+ joined_at: now,
151
+ status: "ACTIVE",
152
+ }, ["user_id", "group_id"]);
153
+ return {
154
+ success: true,
155
+ group,
156
+ membership: reactivated[0],
157
+ };
158
+ }
159
+ const inserted = await membership_service.insert({
160
+ user_id: data.user_id,
161
+ group_id: group.id,
162
+ role_id: (_c = data.role_id) !== null && _c !== void 0 ? _c : null,
163
+ joined_at: now,
164
+ status: "ACTIVE",
165
+ });
166
+ if (!Array.isArray(inserted) || inserted.length === 0) {
167
+ return { success: false, error: "Failed to join group" };
168
+ }
169
+ return { success: true, group, membership: inserted[0] };
170
+ }
171
+ catch (error) {
172
+ const logger = create_app_logger();
173
+ const error_message = sanitize_error_for_user(error, {
174
+ logToConsole: true,
175
+ logToLogger: true,
176
+ logger,
177
+ context: {
178
+ filename: "group_service.ts",
179
+ line_number: 0,
180
+ operation: "join_by_code",
181
+ user_id: data.user_id,
182
+ },
183
+ });
184
+ return { success: false, error: error_message };
185
+ }
186
+ }
187
+ /**
188
+ * Gets a paginated page of a group's active members.
189
+ */
190
+ export async function get_members(adapter, group_id, options = {}) {
191
+ var _a, _b;
192
+ try {
193
+ const membership_service = createCrudService(adapter, "hazo_group_memberships", GROUP_MEMBERSHIPS_CRUD_OPTIONS);
194
+ const limit = (_a = options.limit) !== null && _a !== void 0 ? _a : DEFAULT_MEMBERS_PAGE_SIZE;
195
+ const offset = (_b = options.offset) !== null && _b !== void 0 ? _b : 0;
196
+ const members = await membership_service.list((qb) => qb
197
+ .where("group_id", "eq", group_id)
198
+ .where("status", "eq", "ACTIVE")
199
+ .order("joined_at", "asc")
200
+ .limit(limit)
201
+ .offset(offset));
202
+ const total = await membership_service.findBy({
203
+ group_id,
204
+ status: "ACTIVE",
205
+ });
206
+ return {
207
+ success: true,
208
+ members: members,
209
+ total: Array.isArray(total) ? total.length : 0,
210
+ };
211
+ }
212
+ catch (error) {
213
+ const logger = create_app_logger();
214
+ const error_message = sanitize_error_for_user(error, {
215
+ logToConsole: true,
216
+ logToLogger: true,
217
+ logger,
218
+ context: {
219
+ filename: "group_service.ts",
220
+ line_number: 0,
221
+ operation: "get_members",
222
+ group_id,
223
+ },
224
+ });
225
+ return { success: false, error: error_message };
226
+ }
227
+ }
228
+ /**
229
+ * Gets every group a user has an active membership in.
230
+ */
231
+ export async function get_user_groups(adapter, user_id) {
232
+ try {
233
+ const membership_service = createCrudService(adapter, "hazo_group_memberships", GROUP_MEMBERSHIPS_CRUD_OPTIONS);
234
+ const group_service = createCrudService(adapter, "hazo_groups");
235
+ const memberships = await membership_service.findBy({
236
+ user_id,
237
+ status: "ACTIVE",
238
+ });
239
+ if (!Array.isArray(memberships) || memberships.length === 0) {
240
+ return { success: true, groups: [] };
241
+ }
242
+ const groups = [];
243
+ for (const membership of memberships) {
244
+ const found = await group_service.findBy({ id: membership.group_id });
245
+ if (Array.isArray(found) && found.length > 0) {
246
+ groups.push(to_group_record(found[0]));
247
+ }
248
+ }
249
+ return { success: true, groups };
250
+ }
251
+ catch (error) {
252
+ const logger = create_app_logger();
253
+ const error_message = sanitize_error_for_user(error, {
254
+ logToConsole: true,
255
+ logToLogger: true,
256
+ logger,
257
+ context: {
258
+ filename: "group_service.ts",
259
+ line_number: 0,
260
+ operation: "get_user_groups",
261
+ user_id,
262
+ },
263
+ });
264
+ return { success: false, error: error_message };
265
+ }
266
+ }
@@ -16,6 +16,7 @@ export * from "./firm_service.js";
16
16
  export * from "./post_verification_service.js";
17
17
  export * from "./scope_service.js";
18
18
  export * from "./user_scope_service.js";
19
+ export * from "./group_service.js";
19
20
  export * from "./oauth_service.js";
20
21
  export * from "./branding_service.js";
21
22
  export * from "./google_token_service.js";
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/services/index.ts"],"names":[],"mappings":"AAEA,cAAc,iBAAiB,CAAC;AAChC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,iBAAiB,CAAC;AAChC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,kCAAkC,CAAC;AACjD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iCAAiC,CAAC;AAChD,cAAc,wBAAwB,CAAC;AACvC,cAAc,iBAAiB,CAAC;AAChC,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/services/index.ts"],"names":[],"mappings":"AAEA,cAAc,iBAAiB,CAAC;AAChC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,iBAAiB,CAAC;AAChC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,kCAAkC,CAAC;AACjD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iCAAiC,CAAC;AAChD,cAAc,wBAAwB,CAAC;AACvC,cAAc,iBAAiB,CAAC;AAChC,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC"}
@@ -18,6 +18,7 @@ export * from "./firm_service.js";
18
18
  export * from "./post_verification_service.js";
19
19
  export * from "./scope_service.js";
20
20
  export * from "./user_scope_service.js";
21
+ export * from "./group_service.js";
21
22
  export * from "./oauth_service.js";
22
23
  export * from "./branding_service.js";
23
24
  export * from "./google_token_service.js";
@@ -26,7 +26,7 @@ export declare function GET(request: NextRequest): Promise<NextResponse<{
26
26
  profile_source: {} | null;
27
27
  user_type: string | null;
28
28
  app_user_data: Record<string, unknown> | null;
29
- legal_acceptance_status: "current" | "outdated" | "none";
29
+ legal_acceptance_status: "current" | "none" | "outdated";
30
30
  }[];
31
31
  }>>;
32
32
  /**
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "hazo_auth",
3
- "version": "10.23.3",
3
+ "version": "10.24.0",
4
4
  "description": "Zero-config authentication UI components for Next.js with RBAC, OAuth, scope-based multi-tenancy, and invitations",
5
5
  "keywords": [
6
6
  "authentication",
@@ -276,14 +276,14 @@
276
276
  },
277
277
  "peerDependencies": {
278
278
  "hazo_config": "^2.6.0",
279
- "hazo_connect": "^4.3.1",
279
+ "hazo_connect": "^4.3.3",
280
280
  "hazo_core": "^2.4.0",
281
- "hazo_i18n": "^0.8.1",
281
+ "hazo_i18n": "^0.9.0",
282
282
  "hazo_logs": "^2.3.0",
283
- "hazo_notify": "^6.6.1",
283
+ "hazo_notify": "^6.7.0",
284
284
  "hazo_secure": "^1.8.1",
285
285
  "hazo_theme": "^1.4.0",
286
- "hazo_ui": "^6.13.1",
286
+ "hazo_ui": "^6.14.0",
287
287
  "next": "^14.0.0 || ^15.0.0 || ^16.0.0",
288
288
  "next-auth": "^4.24.0",
289
289
  "react": "^18.0.0 || ^19.0.0",
@@ -363,12 +363,12 @@
363
363
  "eslint-plugin-storybook": "^10.0.6",
364
364
  "hazo_api": "^2.8.0",
365
365
  "hazo_config": "^2.6.0",
366
- "hazo_connect": "^4.3.1",
366
+ "hazo_connect": "^4.3.3",
367
367
  "hazo_core": "^2.4.0",
368
368
  "hazo_logs": "^2.3.0",
369
- "hazo_notify": "^6.6.1",
369
+ "hazo_notify": "^6.7.0",
370
370
  "hazo_theme": "^1.4.0",
371
- "hazo_ui": "^6.13.1",
371
+ "hazo_ui": "^6.14.0",
372
372
  "input-otp": "^1.4.0",
373
373
  "jest": "^30.2.0",
374
374
  "jest-environment-jsdom": "^30.0.0",