@deveye/types 0.25.5 → 0.25.6

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@deveye/types",
3
- "version": "0.25.5",
3
+ "version": "0.25.6",
4
4
  "description": "Shared contracts (types + zod schemas) for DevEye apps",
5
5
  "main": "src/index.ts",
6
6
  "types": "src/index.ts",
@@ -362,6 +362,17 @@ export const FEATURE_REGISTRY: readonly (FeatureDescriptor & { id: WorkspaceFeat
362
362
  hasItems: true,
363
363
  itemNoun: 'lien',
364
364
  shareTier: 'open'
365
+ },
366
+ {
367
+ id: 'whiteboard',
368
+ label: 'Tableau blanc',
369
+ description:
370
+ 'Lecture : les tableaux, et suivre en direct qui y dessine. Écriture : créer un tableau, dessiner, y coller des images, le renommer, le supprimer.',
371
+ icon: 'whiteboard',
372
+ notifies: false,
373
+ hasItems: true,
374
+ itemNoun: 'tableau',
375
+ shareTier: 'open'
365
376
  }
366
377
  ];
367
378
 
@@ -496,7 +507,8 @@ export const PROJECT_LINKED_FEATURES: readonly FeatureId[] = [
496
507
  'audience',
497
508
  'deploy',
498
509
  'uptime',
499
- 'x-hosting'
510
+ 'x-hosting',
511
+ 'whiteboard'
500
512
  ];
501
513
 
502
514
  /** Les fonctionnalités qui savent prévenir, dans l'ordre du registre. */
@@ -41,7 +41,8 @@ export const nativeHomeFeatureIdSchema = z.enum([
41
41
  'mailserver',
42
42
  'convert',
43
43
  'invoicing',
44
- 'shortlinks'
44
+ 'shortlinks',
45
+ 'whiteboard'
45
46
  ]);
46
47
  export type NativeHomeFeatureId = z.infer<typeof nativeHomeFeatureIdSchema>;
47
48
 
@@ -76,22 +76,35 @@ export const liveCursorKindSchema = z.enum([
76
76
  export type LiveCursorKind = z.infer<typeof liveCursorKindSchema>;
77
77
 
78
78
  /**
79
- * Position du curseur dans la surface de la vue. Unités mixtes à dessein :
79
+ * Position du curseur dans la surface de la vue. Celle de la popup, par défaut,
80
+ * a des unités mixtes à dessein :
80
81
  * - `x` est relatif (0..1) à la largeur de la surface, bornée à 1240 px : seule
81
82
  * une fraction reste juste quand les deux fenêtres divergent ;
82
83
  * - `y` est en pixels absolus du contenu, défilement compris : le contenu est
83
84
  * le même des deux côtés, alors qu'une fraction de la hauteur se décalerait
84
85
  * dès qu'une liste est chargée plus loin d'un côté.
85
- * Les bornes de `x` dépassent [0, 1] : le pointeur vit aussi dans les marges,
86
- * et l'écrêter ferait disparaître le curseur d'un pair sur la même page.
86
+ * Une vue qui déclare sa propre surface (un canevas qu'on déplace et qu'on
87
+ * zoome) donne les deux dans ses unités à elle. Les bornes n'écartent que
88
+ * l'absurde : un pointeur vit aussi dans les marges, et l'écrêter ferait
89
+ * disparaître le curseur d'un pair sur la même page.
87
90
  */
88
91
  export const liveCursorSchema = z.object({
89
- x: z.number().min(-10).max(10),
90
- y: z.number().min(-100_000).max(100_000),
92
+ x: z.number().min(-1_000_000).max(1_000_000),
93
+ y: z.number().min(-1_000_000).max(1_000_000),
91
94
  kind: liveCursorKindSchema
92
95
  });
93
96
  export type LiveCursor = z.infer<typeof liveCursorSchema>;
94
97
 
98
+ /**
99
+ * Un canal de curseurs, `feature:clé` : ceux qui partagent la surface d'une vue
100
+ * plutôt que celle de la popup, d'où que vienne leur connexion. Seul le serveur
101
+ * d'un module y assied une connexion (`ctx.live.joinCursors`).
102
+ */
103
+ export const liveCursorChannelSchema = z
104
+ .string()
105
+ .max(96)
106
+ .regex(/^[a-z][a-z0-9-]*:[A-Za-z0-9_.-]{1,64}$/, 'Canal attendu sous la forme feature:clé');
107
+
95
108
  /**
96
109
  * Un pair tel qu'il est diffusé. Ni pseudo ni avatar : `users.avatar` est une
97
110
  * URL de données pouvant atteindre 1,5 Mo, et le roster repart à chaque
@@ -209,6 +222,7 @@ export const TOPIC_FEATURE: Record<NativeLiveTopic, WorkspaceFeatureId | null> =
209
222
  convert: 'convert',
210
223
  invoicing: 'invoicing',
211
224
  shortlinks: 'shortlinks',
225
+ whiteboard: 'whiteboard',
212
226
  workspace: null,
213
227
  home: null,
214
228
  account: null,
@@ -113,7 +113,13 @@ export const workspaceFeatureIdSchema = z.enum([
113
113
  * Liens courts. `read` = voir les liens et leurs statistiques, `write` =
114
114
  * créer un lien, changer sa destination et ses réglages, le supprimer.
115
115
  */
116
- 'shortlinks'
116
+ 'shortlinks',
117
+ /**
118
+ * Tableau blanc. `read` = voir les tableaux et suivre en direct qui y
119
+ * dessine, `write` = créer un tableau, dessiner, y coller des images, le
120
+ * renommer, le supprimer.
121
+ */
122
+ 'whiteboard'
117
123
  ]);
118
124
 
119
125
  export type WorkspaceFeatureId = z.infer<typeof workspaceFeatureIdSchema>;
@@ -1,5 +1,12 @@
1
1
  import { z } from 'zod';
2
- import { liveCursorSchema, livePathSchema, livePeerSchema, liveTopicSchema } from '../domain/live';
2
+ import {
3
+ liveCursorChannelSchema,
4
+ liveCursorSchema,
5
+ livePathSchema,
6
+ livePeerSchema,
7
+ liveTopicSchema
8
+ } from '../domain/live';
9
+ import { userColorSchema } from '../domain/user';
3
10
 
4
11
  /**
5
12
  * Déclare où je suis, et récupère l'état de la salle. L'espace n'est pas dans
@@ -25,11 +32,16 @@ export const liveCommands = [liveHere] as const;
25
32
  export const LIVE_CURSOR_COMMAND = 'live.cursor' as const;
26
33
 
27
34
  /**
28
- * Ce que porte une trame de curseur : des coordonnées, rien d'autre. Ni chemin
29
- * ni espace : la voie rapide court-circuite l'autorisation, le lieu vient du
30
- * dernier `live.here`. `cursor: null` = le pointeur a quitté la surface.
35
+ * Ce que porte une trame de curseur : des coordonnées et leur surface, rien
36
+ * d'autre. Ni chemin ni espace : la voie rapide court-circuite l'autorisation,
37
+ * le lieu vient du dernier `live.here`. `cursor: null` = le pointeur a quitté la
38
+ * surface. `channel` nomme la surface d'une vue, `null` celle de la popup : une
39
+ * trame qui nomme un canal où la connexion n'est pas assise est ignorée.
31
40
  */
32
- export const liveCursorFrameSchema = z.object({ cursor: liveCursorSchema.nullable() });
41
+ export const liveCursorFrameSchema = z.object({
42
+ cursor: liveCursorSchema.nullable(),
43
+ channel: liveCursorChannelSchema.nullable()
44
+ });
33
45
  export type LiveCursorFrame = z.infer<typeof liveCursorFrameSchema>;
34
46
 
35
47
  /**
@@ -111,14 +123,25 @@ export const livePeersPushSchema = z.object({
111
123
  });
112
124
  export type LivePeersPush = z.infer<typeof livePeersPushSchema>;
113
125
 
114
- /** Curseurs des pairs situés au **même chemin exactement** que le destinataire. */
126
+ /**
127
+ * Curseurs des pairs qui partagent la surface du destinataire : ceux du **même
128
+ * chemin exactement**, ou ceux du même canal, d'où qu'ils viennent.
129
+ */
115
130
  export const LIVE_CURSORS_EVENT = 'live.cursors' as const;
116
131
  export const liveCursorsPushSchema = z.object({
117
132
  workspaceId: z.number().int().positive(),
133
+ /** La surface de ces positions : le canal, `null` pour la popup. */
134
+ channel: liveCursorChannelSchema.nullable(),
118
135
  cursors: z.array(
119
136
  z.object({
120
137
  connId: z.string().min(1),
121
138
  userId: z.number().int().positive(),
139
+ color: userColorSchema,
140
+ /**
141
+ * Le pseudo d'un pair de canal, qui peut venir d'un autre espace ;
142
+ * `null` sur la popup, où il se lit dans les membres de l'espace.
143
+ */
144
+ name: z.string().nullable(),
122
145
  cursor: liveCursorSchema
123
146
  })
124
147
  )
package/src/index.ts CHANGED
@@ -573,6 +573,7 @@ export type {
573
573
  ShortcutTemplate
574
574
  } from './domain/home';
575
575
  export {
576
+ liveCursorChannelSchema,
576
577
  liveCursorKindSchema,
577
578
  liveCursorSchema,
578
579
  livePathGate,
@@ -28,6 +28,7 @@ declare module 'deveye-sdk-client' {
28
28
  FeatureAccess,
29
29
  FeatureDomain,
30
30
  FeatureId,
31
+ LiveCursor,
31
32
  MinimalUser,
32
33
  PathExclusionKind,
33
34
  RequestProgress,
@@ -846,6 +847,16 @@ declare module 'deveye-sdk-client' {
846
847
  input: z.input<Extract<M['commands'][number], { command: N }>['input'] & ZodType>,
847
848
  opts?: SendOptions
848
849
  ): Promise<z.output<Extract<M['commands'][number], { command: N }>['output'] & ZodType>>;
850
+ /**
851
+ * Fire and forget: no reply, no timeout, no trace entry. For what is
852
+ * re-sent several times a second (a pointer position); silently dropped
853
+ * while the socket is closed or backed up. The server still validates
854
+ * and checks access as for `send`.
855
+ */
856
+ post<N extends M['commands'][number]['command']>(
857
+ name: N,
858
+ input: z.input<Extract<M['commands'][number], { command: N }>['input'] & ZodType>
859
+ ): void;
849
860
  };
850
861
 
851
862
  // ── Password-based encryption (secrecy) ────────────────────────────────
@@ -1206,6 +1217,39 @@ declare module 'deveye-sdk-client' {
1206
1217
  * (a table explorer in expanded mode).
1207
1218
  */
1208
1219
  export function useRequestPopupWidth(px: number | null): void;
1220
+ /**
1221
+ * A view's own cursor surface: where DevEye's live cursors are placed,
1222
+ * instead of the popup. For a canvas each viewer pans and zooms, where a
1223
+ * point relative to the popup designates nothing. Your coordinates are
1224
+ * yours (a scene's), within a million either way.
1225
+ */
1226
+ export interface LiveCursorSurface {
1227
+ /** The cursor channel your server seated this connection in (`ctx.live.joinCursors`). */
1228
+ channel: string;
1229
+ /** A screen point (client pixels) in your coordinates; `null` off the surface. */
1230
+ fromScreen(clientX: number, clientY: number): { x: number; y: number } | null;
1231
+ /** Back to client pixels; `null` where the surface does not show it. */
1232
+ toScreen(x: number, y: number): { x: number; y: number } | null;
1233
+ /** Calls `onChange` whenever `toScreen` would answer differently (a pan, a zoom). */
1234
+ subscribe(onChange: () => void): () => void;
1235
+ }
1236
+ /**
1237
+ * Places DevEye's live cursors on `surface` while the calling view is the
1238
+ * one open: the same cursors, cadence, glide, bubble and account switch as
1239
+ * anywhere else, between the connections seated in `surface.channel`
1240
+ * rather than the peers at the same path. `null` gives the popup back. Pass
1241
+ * a stable object: a new one re-declares the surface.
1242
+ */
1243
+ export function useLiveCursorSurface(surface: LiveCursorSurface | null): void;
1244
+ /**
1245
+ * The peers' raw positions in `channel`, as they arrive (about twenty times
1246
+ * a second), for what your view draws with them (a laser trail). DevEye
1247
+ * draws the cursors themselves.
1248
+ */
1249
+ export function onLiveCursors(
1250
+ channel: string,
1251
+ cb: (cursors: readonly { connId: string; userId: number; cursor: LiveCursor }[]) => void
1252
+ ): () => void;
1209
1253
 
1210
1254
  // Change events re-exported for convenience in handlers.
1211
1255
  export type InputChange = ChangeEvent<HTMLInputElement>;
package/src/sdk/client.ts CHANGED
@@ -477,6 +477,43 @@ export interface HostingClientProvider {
477
477
  }>;
478
478
  }
479
479
 
480
+ /** A board of the workspace, as the Whiteboard client provider lists it for a project's picker. */
481
+ export interface WhiteboardLinkedCandidate {
482
+ id: number;
483
+ name: string;
484
+ /** Projected here from another workspace. */
485
+ foreign?: boolean;
486
+ }
487
+
488
+ /**
489
+ * What the Whiteboard module offers the host's screens under
490
+ * `WHITEBOARD_CLIENT_PROVIDER`: the workspace's boards, a linked board shown
491
+ * inside a project's tab, and the feature's own board dialog.
492
+ */
493
+ export interface WhiteboardClientProvider {
494
+ /** The workspace's boards, in the module's own order. */
495
+ listBoards(): Promise<readonly WhiteboardLinkedCandidate[]>;
496
+ /**
497
+ * The given boards, summarised for a project's dashboard tile, in ONE
498
+ * round trip. An id the caller cannot read, or that is gone, comes back
499
+ * `unavailable`, never as a throw.
500
+ */
501
+ summarize(boardIds: readonly number[]): Promise<readonly SdkTileSummary[]>;
502
+ /**
503
+ * A board linked to a project: its title, its preview, when it last
504
+ * changed, and the way into the editor. Loads itself, follows the
505
+ * feature's invalidations, and renders the host's "unlink" as its
506
+ * trailing action.
507
+ */
508
+ LinkedBoard: ComponentType<{ boardId: number; canWrite: boolean; onUnlink: () => void }>;
509
+ /** The feature's board form, to create a board from a project. */
510
+ BoardDialog: ComponentType<{
511
+ open: boolean;
512
+ onClose: () => void;
513
+ onSaved: (boardId: number) => void;
514
+ }>;
515
+ }
516
+
480
517
  /**
481
518
  * What the Invoicing module offers other screens under
482
519
  * `INVOICING_CLIENT_PROVIDER`. It sends Invoicing's own command under the
@@ -258,7 +258,7 @@ export interface FeatureLink {
258
258
  }
259
259
 
260
260
  /** Hard cap on `links`: the "About" card stays a card. */
261
- export const MAX_FEATURE_LINKS = 6;
261
+ export const MAX_FEATURE_LINKS = 7;
262
262
 
263
263
  export interface FeatureManifest<Id extends FeatureId = FeatureId> {
264
264
  /** External modules: `x-<slug>`. Native features keep their enum id. */
@@ -638,6 +638,32 @@ export interface HostingItemsProvider {
638
638
  */
639
639
  export const HOSTING_CLIENT_PROVIDER = 'hosting.client' as const;
640
640
 
641
+ /**
642
+ * Key under `FeatureService.providers` for the whiteboards the app's Projects
643
+ * feature links to: same shape and same reason as `UPTIME_ITEMS_PROVIDER`
644
+ * (`ft_projects_whiteboard_links` is Projects' table).
645
+ */
646
+ export const WHITEBOARD_ITEMS_PROVIDER = 'whiteboard.items' as const;
647
+
648
+ export interface WhiteboardItemsProvider {
649
+ /** Is this board visible from this workspace: its home, or one it is projected into? */
650
+ exists(boardId: number, workspaceId: number): Promise<boolean>;
651
+ /**
652
+ * The item's display name as seen from `workspaceId` (its home, or a
653
+ * workspace it is projected into): the provider resolves the home and its
654
+ * OPEN cipher itself. `null` when it is gone or unreadable.
655
+ */
656
+ labelOf(boardId: number, workspaceId: number): Promise<string | null>;
657
+ }
658
+
659
+ /**
660
+ * Key under `FeatureClient.providers` for the Whiteboard pieces the app's
661
+ * Projects screens compose: the list of the workspace's boards, a linked
662
+ * board shown inside a project's tab, and the feature's own board dialog.
663
+ * The contract types live in `@deveye/types/sdk/client`.
664
+ */
665
+ export const WHITEBOARD_CLIENT_PROVIDER = 'whiteboard.client' as const;
666
+
641
667
  /**
642
668
  * Key of what Projects knows about the items of OTHER features: the projects
643
669
  * of the workspace that link them (a module's list shows how many projects use
package/src/sdk/server.ts CHANGED
@@ -1119,6 +1119,18 @@ export interface SdkLive {
1119
1119
  * is never attached, so it can never be mistaken for a reply.
1120
1120
  */
1121
1121
  publish(workspaceId: number, event: string, payload: unknown): void;
1122
+ /**
1123
+ * {@link SdkLive.publish}, narrowed to the connections of these accounts:
1124
+ * the participants of something open, when the rest of the room may not
1125
+ * see it (an item its role hides from a member). An empty list sends
1126
+ * nothing.
1127
+ */
1128
+ publishTo(
1129
+ workspaceId: number,
1130
+ userIds: readonly number[],
1131
+ event: string,
1132
+ payload: unknown
1133
+ ): void;
1122
1134
  /** {@link SdkContextLive.accountChanged}, from a service (a webhook, a ticker). */
1123
1135
  accountChanged(userId: number): void;
1124
1136
  /** {@link SdkContextLive.pendingChanged}, from a service or a public route (a report just filed). */
@@ -1133,6 +1145,24 @@ export interface SdkLive {
1133
1145
  export interface SdkContextLive {
1134
1146
  /** {@link SdkLive.publish}, in the workspace of the call. */
1135
1147
  publish(event: string, payload: unknown): void;
1148
+ /**
1149
+ * Seats the caller's connection in YOUR cursor channel `key` (capability
1150
+ * `'live.publish'`): for a view with its own cursor surface (a canvas
1151
+ * each viewer pans and zooms), whose participants may sit in different
1152
+ * workspaces (a projected item). While the client declares that surface
1153
+ * (`useLiveCursorSurface`), DevEye's cursors and bubble go between the
1154
+ * connections seated there, and only them. Check first that the caller
1155
+ * may see the item: the host checks nothing more. The seat lasts until
1156
+ * {@link SdkContextLive.leaveCursors}, a switch to another workspace, the
1157
+ * loss of `read` on your feature or the socket closing.
1158
+ *
1159
+ * Resolves with the channel to hand the client and the caller's
1160
+ * connection id, the one its cursor carries to the others; `null` outside
1161
+ * a browser socket (a test), where there is nothing to seat.
1162
+ */
1163
+ joinCursors(key: string): Promise<{ channel: string; connId: string } | null>;
1164
+ /** Gets the caller's connection out of the cursor channel `key`, if it sits there. */
1165
+ leaveCursors(key: string): void;
1136
1166
  /**
1137
1167
  * Something of this ACCOUNT changed (its plan, its subscription): its open
1138
1168
  * clients, in whatever workspace they sit, re-fetch the account plan and
@@ -139,8 +139,13 @@ export interface RecordedCalls {
139
139
  }[];
140
140
  /** Instants pinned through `telemetry.pinInstant`. */
141
141
  pinnedInstants: { deviceId: string; ts: number }[];
142
- /** Frames pushed through `live.publish`, in order. */
143
- livePublishes: { workspaceId: number; event: string; payload: unknown }[];
142
+ /** Frames pushed through `live.publish` and `live.publishTo` (with its `userIds`), in order. */
143
+ livePublishes: {
144
+ workspaceId: number;
145
+ event: string;
146
+ payload: unknown;
147
+ userIds?: readonly number[];
148
+ }[];
144
149
  /** Accounts beaten through `live.accountChanged`, in order. */
145
150
  accountChanges: number[];
146
151
  /** How many times `live.pendingChanged` was called. */
@@ -646,6 +651,9 @@ export function createTestContext<Repo = undefined>(
646
651
  publish(event, payload) {
647
652
  recorded.livePublishes.push({ workspaceId, event, payload });
648
653
  },
654
+ // No browser socket here, as in a test of the real host: nobody to seat.
655
+ joinCursors: () => Promise.resolve(null),
656
+ leaveCursors: () => undefined,
649
657
  accountChanged(userId) {
650
658
  recorded.accountChanges.push(userId);
651
659
  },
@@ -939,6 +947,9 @@ export function createTestServiceDeps<Repo = undefined>(
939
947
  publish(workspaceId, event, payload) {
940
948
  recorded.livePublishes.push({ workspaceId, event, payload });
941
949
  },
950
+ publishTo(workspaceId, userIds, event, payload) {
951
+ recorded.livePublishes.push({ workspaceId, event, payload, userIds: [...userIds] });
952
+ },
942
953
  accountChanged(userId) {
943
954
  recorded.accountChanges.push(userId);
944
955
  },