@lanework/contracts 0.4.1 → 0.5.1

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/src/avatar.ts ADDED
@@ -0,0 +1,191 @@
1
+ // A project's chosen avatar: a letter, an emoji or an icon on a colour from a
2
+ // fixed palette. Synced with the project, so every machine and teammate sees
3
+ // the same mark. A project without one keeps its default mark: its owner's
4
+ // GitHub icon, or the letter tile.
5
+
6
+ /**
7
+ * Colour ids, never hex: there are no custom colours. Each app draws an id
8
+ * its own way, in light and dark.
9
+ */
10
+ export const PROJECT_AVATAR_COLORS = [
11
+ // solid
12
+ "slate",
13
+ "red",
14
+ "orange",
15
+ "amber",
16
+ "green",
17
+ "teal",
18
+ "sky",
19
+ "blue",
20
+ "violet",
21
+ "pink",
22
+ // gradient
23
+ "sunset",
24
+ "ocean",
25
+ "forest",
26
+ "candy",
27
+ "dusk",
28
+ "aurora",
29
+ ] as const;
30
+
31
+ export type ProjectAvatarColor = (typeof PROJECT_AVATAR_COLORS)[number];
32
+
33
+ /**
34
+ * The icons a project may pick: export names from `@hugeicons/core-free-icons`
35
+ * (checked against 4.3.0). A curated list, not the whole set, so an app only
36
+ * bundles these. Removing a name is a breaking change; adding one is minor.
37
+ */
38
+ export const PROJECT_AVATAR_ICONS = [
39
+ // work and code
40
+ "Rocket01Icon",
41
+ "SourceCodeIcon",
42
+ "ComputerTerminal01Icon",
43
+ "GitBranchIcon",
44
+ "Bug01Icon",
45
+ "Database01Icon",
46
+ "ServerStack01Icon",
47
+ "CloudIcon",
48
+ "Globe02Icon",
49
+ "Link01Icon",
50
+ "Layers01Icon",
51
+ "Package01Icon",
52
+ "DashboardSquare01Icon",
53
+ "Settings01Icon",
54
+ "Wrench01Icon",
55
+ "Shield01Icon",
56
+ "LockIcon",
57
+ "Robot01Icon",
58
+ "AiBrain01Icon",
59
+ "SparklesIcon",
60
+ "MagicWand01Icon",
61
+ // business
62
+ "Briefcase01Icon",
63
+ "Analytics01Icon",
64
+ "ChartLineData01Icon",
65
+ "Wallet01Icon",
66
+ "CreditCardIcon",
67
+ "ShoppingCart01Icon",
68
+ "ShoppingBag01Icon",
69
+ "Store01Icon",
70
+ "Target02Icon",
71
+ "Flag01Icon",
72
+ "Award01Icon",
73
+ // communication and documents
74
+ "Mail01Icon",
75
+ "BubbleChatIcon",
76
+ "Notification01Icon",
77
+ "Calendar03Icon",
78
+ "Clock01Icon",
79
+ "Folder01Icon",
80
+ "File01Icon",
81
+ "Book02Icon",
82
+ "School01Icon",
83
+ "PencilEdit01Icon",
84
+ // people and places
85
+ "Home01Icon",
86
+ "UserIcon",
87
+ "UserGroupIcon",
88
+ "Location01Icon",
89
+ "Compass01Icon",
90
+ "Car01Icon",
91
+ "Airplane01Icon",
92
+ "AnchorIcon",
93
+ // media and play
94
+ "PaintBoardIcon",
95
+ "ColorsIcon",
96
+ "Image01Icon",
97
+ "Camera01Icon",
98
+ "MusicNote01Icon",
99
+ "HeadphonesIcon",
100
+ "GameController01Icon",
101
+ "PuzzleIcon",
102
+ // science
103
+ "Atom01Icon",
104
+ "TestTube01Icon",
105
+ "Idea01Icon",
106
+ // nature and things
107
+ "Sun01Icon",
108
+ "Moon02Icon",
109
+ "FlashIcon",
110
+ "FireIcon",
111
+ "Leaf01Icon",
112
+ "Plant01Icon",
113
+ "Tree01Icon",
114
+ "Coffee01Icon",
115
+ "Pizza01Icon",
116
+ "BirthdayCakeIcon",
117
+ "GiftIcon",
118
+ "Diamond01Icon",
119
+ "CrownIcon",
120
+ "StarIcon",
121
+ "FavouriteIcon",
122
+ "SmileIcon",
123
+ ] as const;
124
+
125
+ export type ProjectAvatarIcon = (typeof PROJECT_AVATAR_ICONS)[number];
126
+
127
+ /**
128
+ * A project's chosen avatar. On the wire `avatar?: ProjectAvatar | null`:
129
+ * absent leaves it alone, `null` clears it back to the default mark.
130
+ */
131
+ export type ProjectAvatar =
132
+ /** 1-2 characters (graphemes), e.g. initials. */
133
+ | { kind: "letter"; text: string; color: ProjectAvatarColor }
134
+ /** Exactly one emoji grapheme. */
135
+ | { kind: "emoji"; emoji: string; color: ProjectAvatarColor }
136
+ /** A name from {@link PROJECT_AVATAR_ICONS}. */
137
+ | { kind: "icon"; icon: ProjectAvatarIcon; color: ProjectAvatarColor };
138
+
139
+ const COLORS: ReadonlySet<string> = new Set(PROJECT_AVATAR_COLORS);
140
+ const ICONS: ReadonlySet<string> = new Set(PROJECT_AVATAR_ICONS);
141
+ const GRAPHEMES = new Intl.Segmenter(undefined, { granularity: "grapheme" });
142
+ // Control and format characters (zero-width joiners, direction marks).
143
+ const CONTROL = /\p{Cc}|\p{Cf}/u;
144
+ // A grapheme that is an emoji: a pictograph, a flag (regional indicators) or
145
+ // a keycap.
146
+ const EMOJI = /\p{Extended_Pictographic}|\p{Regional_Indicator}|⃣/u;
147
+
148
+ function graphemes(text: string): string[] {
149
+ return Array.from(GRAPHEMES.segment(text), (s) => s.segment);
150
+ }
151
+
152
+ function isObject(value: unknown): value is Record<string, unknown> {
153
+ return typeof value === "object" && value !== null && !Array.isArray(value);
154
+ }
155
+
156
+ /**
157
+ * Read an avatar from untrusted input, strictly: an unknown kind, colour or
158
+ * icon, letter text that is empty, blank or over 2 characters, or an emoji
159
+ * that is not exactly one emoji grapheme gives null. Extra keys are dropped.
160
+ */
161
+ export function parseProjectAvatar(value: unknown): ProjectAvatar | null {
162
+ if (!isObject(value)) return null;
163
+ const { kind, color } = value;
164
+ if (typeof color !== "string" || !COLORS.has(color)) return null;
165
+ const c = color as ProjectAvatarColor;
166
+
167
+ switch (kind) {
168
+ case "letter": {
169
+ const { text } = value;
170
+ if (typeof text !== "string" || text.trim() !== text) return null;
171
+ if (CONTROL.test(text)) return null;
172
+ const n = graphemes(text).length;
173
+ if (n < 1 || n > 2) return null;
174
+ return { kind, text, color: c };
175
+ }
176
+ case "emoji": {
177
+ const { emoji } = value;
178
+ if (typeof emoji !== "string") return null;
179
+ const g = graphemes(emoji);
180
+ if (g.length !== 1 || !EMOJI.test(emoji)) return null;
181
+ return { kind, emoji, color: c };
182
+ }
183
+ case "icon": {
184
+ const { icon } = value;
185
+ if (typeof icon !== "string" || !ICONS.has(icon)) return null;
186
+ return { kind, icon: icon as ProjectAvatarIcon, color: c };
187
+ }
188
+ default:
189
+ return null;
190
+ }
191
+ }
package/src/index.ts CHANGED
@@ -9,6 +9,7 @@
9
9
 
10
10
  export * from "./agent-notes";
11
11
  export * from "./auth";
12
+ export * from "./avatar";
12
13
  export * from "./boards";
13
14
  export * from "./checkpoints";
14
15
  export * from "./common";
package/src/sync.ts CHANGED
@@ -2,6 +2,7 @@
2
2
  // only; `/v1/workspaces` is the session twin and refuses a machine with 401.
3
3
  // Derived from the server's `routes/sync.ts`.
4
4
 
5
+ import type { ProjectAvatar } from "./avatar";
5
6
  import type { IsoDate } from "./common";
6
7
 
7
8
  export interface SyncProfile {
@@ -20,6 +21,12 @@ export interface SyncWorkspace {
20
21
  color: string | null;
21
22
  /** The R2 key of the project's icon, or null. */
22
23
  iconKey: string | null;
24
+ /**
25
+ * The avatar picked for the project, or null for the default mark (the
26
+ * owner's GitHub icon, or the letter tile). Absent from a server older
27
+ * than 0.5.0.
28
+ */
29
+ avatar?: ProjectAvatar | null;
23
30
  laneworkStyle: boolean;
24
31
  baseBranch: string | null;
25
32
  addedAt: IsoDate;
@@ -117,6 +124,11 @@ export interface SyncWorkspaceSlugTakenError {
117
124
  export interface SyncWorkspacePatchRequest {
118
125
  name?: string;
119
126
  color?: string | null;
127
+ /**
128
+ * Set the avatar; `null` clears it back to the default mark. The server
129
+ * refuses with 400 what `parseProjectAvatar` refuses.
130
+ */
131
+ avatar?: ProjectAvatar | null;
120
132
  baseBranch?: string | null;
121
133
  laneworkStyle?: boolean;
122
134
  autoRoute?: boolean;
@@ -128,6 +140,7 @@ export interface SyncWorkspacePatchResponse {
128
140
  slug: string;
129
141
  name: string;
130
142
  color: string | null;
143
+ avatar?: ProjectAvatar | null;
131
144
  baseBranch: string | null;
132
145
  };
133
146
  }