@deveye/types 0.15.0

package/src/protocol/envelope.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+import { ProtocolErrorSchema } from './error';
+
+/**
+ * WebSocket envelope shared between client and server.
+ *
+ * Client sends `ClientMessage` with `command`, `requestId` and `payload`.
+ * Server replies with `ServerMessage` whose `requestId` matches; payload is a
+ * `Result`-shaped object (success or protocol error). The server may also push
+ * unsolicited events with no `requestId`.
+ */
+
+export const clientMessageSchema = z.object({
+    requestId: z.string().min(1),
+    command: z.string().min(1),
+    /**
+     * Espace de travail visé par la commande. Absent → l'espace personnel de
+     * l'appelant.
+     *
+     * Il vit sur l'enveloppe, et non dans le `payload` de chaque commande, pour
+     * trois raisons : aucun schéma d'entrée ne porte de `workspaceId`, aucun site
+     * d'appel client ne le passe à la main (`ws.send` l'estampille), et le
+     * serveur n'a qu'un seul point de résolution et d'autorisation. Le tenir dans
+     * un état de session côté serveur serait plus fragile : la socket se
+     * reconnecte seule (backoff, retour de focus) et une commande émise avant la
+     * ré-activation viserait le mauvais espace — ici chaque message se décrit
+     * lui-même.
+     */
+    workspaceId: z.number().int().positive().optional(),
+    payload: z.unknown()
+});
+
+export type ClientMessage = z.infer<typeof clientMessageSchema>;
+
+export const serverMessageSchema = z.object({
+    requestId: z.string().min(1).optional(),
+    command: z.string().min(1),
+    payload: z.discriminatedUnion('ok', [
+        z.object({ ok: z.literal(true), data: z.unknown() }),
+        z.object({ ok: z.literal(false), error: ProtocolErrorSchema })
+    ])
+});
+
+export type ServerMessage = z.infer<typeof serverMessageSchema>;
+
+export type ConnectionState = 'idle' | 'connecting' | 'open' | 'closing' | 'closed' | 'error';

package/src/protocol/error.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+
+export const ErrorCodeSchema = z.enum([
+    'auth_required',
+    'auth_invalid',
+    'auth_expired',
+    'forbidden',
+    'not_found',
+    'conflict',
+    'validation',
+    'rate_limited',
+    'internal',
+    'unsupported_version',
+    // Password-based encryption is enabled but the session has not yet been
+    // unlocked with the user's password. The client should prompt for it.
+    'locked'
+]);
+
+export type ErrorCode = z.infer<typeof ErrorCodeSchema>;
+
+export const ProtocolErrorSchema = z.object({
+    code: ErrorCodeSchema,
+    message: z.string(),
+    details: z.unknown().optional()
+});
+
+export type ProtocolError = z.infer<typeof ProtocolErrorSchema>;

package/src/protocol/result.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+import { ProtocolErrorSchema, type ErrorCode, type ProtocolError } from './error';
+
+export type Result<T, E = ProtocolError> = { ok: true; data: T } | { ok: false; error: E };
+
+export const ok = <T>(data: T): Result<T> => ({ ok: true, data });
+
+export const err = (code: ErrorCode, message: string, details?: unknown): Result<never> => ({
+    ok: false,
+    error: { code, message, ...(details !== undefined ? { details } : {}) }
+});
+
+export const resultSchema = <T extends z.ZodTypeAny>(data: T) =>
+    z.discriminatedUnion('ok', [
+        z.object({ ok: z.literal(true), data }),
+        z.object({ ok: z.literal(false), error: ProtocolErrorSchema })
+    ]);

package/src/protocol/version.ts

@@ -0,0 +1,6 @@
+/**
+ * Protocol version negotiated between client and server.
+ * Bump on any breaking change to wire format, feature schemas or error codes.
+ */
+export const PROTOCOL_VERSION = '0.3.0' as const;
+export type ProtocolVersion = typeof PROTOCOL_VERSION;

package/src/sdk/client-ambient.d.ts

@@ -0,0 +1,238 @@
+/**
+ * Ambient declaration of `deveye-sdk-client` — the runtime barrel the APP
+ * provides when a feature module is compiled in (resolved by alias inside
+ * DevEye). The module itself is app code and is published nowhere; this file
+ * is its typed portrait, so a module repo can `tsc --noEmit` standalone.
+ *
+ * How it is consumed:
+ *  - a module repo (the template) pulls it into its standalone typecheck via
+ *    one tsconfig `include` entry pointing at this file in node_modules;
+ *  - DevEye itself verifies MECHANICALLY that the real barrel honours this
+ *    declaration (`client/npm run check:sdk`): a drift breaks the app's CI,
+ *    never a third-party build.
+ *
+ * Extend it when the app's stable surface grows — same gesture as before,
+ * one file instead of one per module repo.
+ */
+declare module 'deveye-sdk-client' {
+    import type {
+        ButtonHTMLAttributes,
+        ChangeEvent,
+        ComponentType,
+        CSSProperties,
+        InputHTMLAttributes,
+        ReactNode,
+        SelectHTMLAttributes
+    } from 'react';
+    import type { z, ZodType } from 'zod';
+    import type { FeatureAccess, FeatureId, WorkspaceCapability } from 'deveye-types';
+    import type { FeatureManifest } from 'deveye-types/sdk';
+
+    // ── UI kit ─────────────────────────────────────────────────────────────
+    export const Button: ComponentType<
+        ButtonHTMLAttributes<HTMLButtonElement> & {
+            variant?: 'primary' | 'secondary' | 'danger' | 'ghost';
+            icon?: string;
+        }
+    >;
+    export const TextInput: ComponentType<
+        InputHTMLAttributes<HTMLInputElement> & { enableShowHideButton?: boolean }
+    >;
+    export const SelectInput: ComponentType<SelectHTMLAttributes<HTMLSelectElement>>;
+    export const Checkbox: ComponentType<{
+        checked: boolean;
+        /** Receives the state AFTER the click — no event to unwrap. */
+        onChange: (checked: boolean) => void;
+        children?: ReactNode;
+        disabled?: boolean;
+        /** Required when there is no visible label. */
+        'aria-label'?: string;
+    }>;
+    export const Switch: ComponentType<{
+        checked: boolean;
+        onChange: (checked: boolean) => void;
+        label?: string;
+        hint?: string;
+        disabled?: boolean;
+        'aria-label'?: string;
+    }>;
+    export function SegmentedControl<T extends string>(props: {
+        value: T;
+        options: readonly { value: T; label: string; title?: string }[];
+        onChange: (value: T) => void;
+        className?: string;
+        'aria-label'?: string;
+        disabled?: boolean;
+    }): ReactNode;
+    export const Dialog: ComponentType<{
+        open: boolean;
+        onClose: () => void;
+        title?: string;
+        description?: ReactNode;
+        children?: ReactNode;
+        footer?: ReactNode;
+        /** Extra action in the top-right corner, left of the close button. */
+        headerAction?: ReactNode;
+        width?: number;
+        onSubmit?: () => void;
+        fill?: boolean;
+        holdSecrecy?: boolean;
+    }>;
+    export const StatusBadge: ComponentType<{
+        tone?: 'online' | 'offline' | 'success' | 'warning' | 'danger' | 'accent' | 'neutral';
+        /** Show the leading status dot (default true). */
+        dot?: boolean;
+        children: ReactNode;
+        className?: string;
+    }>;
+    /** One confirmation dialog for the whole app — see ConfirmDialog. */
+    export interface ConfirmRequest {
+        title: string;
+        description?: ReactNode;
+        confirmLabel?: string;
+        /** `primary` for a reversible action; `danger` (default) otherwise. */
+        tone?: 'danger' | 'primary';
+        onConfirm: () => void;
+    }
+    export const ConfirmDialog: ComponentType<{
+        /** The pending request, or `null` when nothing awaits confirmation. */
+        request: ConfirmRequest | null;
+        onClose: () => void;
+        busy?: boolean;
+    }>;
+    export const FeatureSettingsButton: ComponentType<{
+        scope:
+            | { kind: 'feature'; feature: FeatureId }
+            | { kind: 'item'; feature: FeatureId; itemId: number; itemLabel: string };
+        variant?: 'primary' | 'secondary' | 'danger' | 'ghost';
+        label?: string;
+    }>;
+    /** The canonical settings row classes (channelRow, field, sectionHint...). */
+    export const settingsStyles: Readonly<Record<string, string>>;
+
+    // ── Server push events ─────────────────────────────────────────────────
+    /** Typed push subscription: filters `event`, safeParses, drops mismatches. */
+    export function onServerEvent<T>(
+        event: string,
+        schema: ZodType<T>,
+        cb: (payload: T) => void
+    ): () => void;
+    /** Fires now if the socket is open, then on every reopen (resubscribe primitive). */
+    export function onSocketOpen(cb: () => void): () => void;
+    /** Whether the socket is open right now (to tell a real error from an outage). */
+    export function isSocketOpen(): boolean;
+
+    // ── Data ───────────────────────────────────────────────────────────────
+    /**
+     * A resource key an EXTERNAL module may own: `x-<slug>.<name>`, as listed
+     * in its manifest `resources`. The app's bus is typed on the closed union
+     * of native keys plus this shape — an arbitrary string is refused there,
+     * so it is refused here too.
+     */
+    export type ExternalResourceKey = `x-${string}.${string}`;
+    export function useResource<T>(
+        key: ExternalResourceKey,
+        load: () => Promise<T>,
+        fallback: string,
+        deps?: readonly unknown[]
+    ): { data: T | null; error: string | null; loading: boolean; reload: () => void };
+    export function invalidate(...keys: ExternalResourceKey[]): void;
+    export function useResourceVersion(key: ExternalResourceKey): number;
+    /** Imperative subscription to one resource key's invalidations. Returns the unsubscribe. */
+    export function onResourceChange(key: ExternalResourceKey, cb: () => void): () => void;
+    export function humanizeError(error: unknown, fallback: string): string;
+    export function featureApi<const M extends FeatureManifest>(
+        manifest: M
+    ): {
+        send<N extends M['commands'][number]['command']>(
+            name: N,
+            input: z.input<Extract<M['commands'][number], { command: N }>['input'] & ZodType>,
+            /** `timeoutMs` stretches the wait for a command that queries a slow third party. */
+            opts?: { timeoutMs?: number }
+        ): Promise<z.output<Extract<M['commands'][number], { command: N }>['output'] & ZodType>>;
+    };
+
+    // ── Password-based encryption (secrecy) ────────────────────────────────
+    // The surface any feature needs when one of its commands can answer
+    // `locked` (contracts stored with `'private'` encryption server-side).
+    export interface SecrecyState {
+        /** True when password-based encryption is enabled for the account. */
+        enabled: boolean;
+        /** True while the session holds the unlocked key. */
+        unlocked: boolean;
+    }
+    /** Live lock state of the session (shared with the topbar widget and the global prompt). */
+    export function useSecrecy(): SecrecyState;
+    /** Resolves once the session is unlocked, opening the global prompt if needed. Rejects on cancel. */
+    export function ensureSecrecyUnlocked(): Promise<void>;
+    /** Runs `run`; on a `locked` error, opens the unlock prompt and retries once. */
+    export function withSecrecy<T>(run: () => Promise<T>): Promise<T>;
+
+    // ── Live ───────────────────────────────────────────────────────────────
+    export type LiveSegmentKind = 'view' | 'l1' | 'l2' | 'l3' | 'l4';
+    export function useLiveSegment(
+        kind: LiveSegmentKind,
+        value: string | null
+    ): { value: string | null } | null;
+    export function useLiveOutline(kind: LiveSegmentKind, value: string | null): LiveOutlineProps;
+    export function useLiveOutlines(
+        kind: LiveSegmentKind
+    ): (value: string | null) => LiveOutlineProps;
+    export function useLiveItemTarget(
+        kind: LiveSegmentKind,
+        value: string | null,
+        ready: boolean,
+        onTarget: (value: string | null) => void
+    ): void;
+    export function useTypers(): { connId: string; userId: number }[];
+    export function useTypingSignal(): { onInput: () => void; stop: () => void };
+
+    // ── Shared helpers ─────────────────────────────────────────────────────
+    /** Byte size with French units (o / Ko / Mo / Go). */
+    export function formatBytesFr(bytes: number): string;
+    /** Folder picker over an enrolled device's filesystem (shared with Backup). */
+    export const DeviceFolderPicker: ComponentType<{
+        open: boolean;
+        deviceId: string;
+        deviceName: string;
+        onClose: () => void;
+        /** Called with the absolute path of the folder picked on the device. */
+        onPick: (path: string) => void;
+        /** What the folder is for, said by the caller. */
+        description?: string;
+    }>;
+    /** The workspace's enrolled devices, live (a polled store, not a bare list). */
+    export function useDevices(): {
+        devices: { id: string; name: string; online: boolean }[];
+        loading: boolean;
+        error: string | null;
+        refresh: () => Promise<void>;
+    };
+    export interface LiveOutlineProps {
+        'data-live-peer'?: true;
+        style?: CSSProperties;
+    }
+
+    // ── Rights and workspace ───────────────────────────────────────────────
+    export function useWorkspacePermissions(): {
+        isOwner: boolean;
+        can: (c: WorkspaceCapability) => boolean;
+        canFeature: (f: FeatureId, level?: FeatureAccess) => boolean;
+        canChannels: (f: FeatureId) => boolean;
+        canExtra: (f: FeatureId, key: string) => boolean;
+        extraValue: (
+            f: FeatureId,
+            key: string,
+            spec: { default: string; ownerValue: string }
+        ) => string;
+    };
+    export function useActiveWorkspace(): {
+        id: number;
+        kind: 'personal' | 'shared';
+        name: string;
+    } | null;
+    export function useFeatureLifecycle(hooks: { onUnmount?: () => void }): void;
+
+    // Change events re-exported for convenience in handlers.
+    export type InputChange = ChangeEvent<HTMLInputElement>;
+}

package/src/sdk/client.ts

@@ -0,0 +1,66 @@
+import type { ComponentType } from 'react';
+
+/**
+ * Client-side SDK contracts: what your package's `./client` entry exports and
+ * what your components receive.
+ *
+ * Your client code imports its runtime helpers (UI kit, `useResource`,
+ * `featureApi`, live hooks, permissions) from `deveye-sdk-client`, which the
+ * app provides when your module is compiled in. This file only carries the
+ * shapes both sides must agree on.
+ */
+
+/** The scope a settings panel is opened for. */
+export type SdkSettingsScope =
+    { kind: 'feature' } | { kind: 'item'; itemId: number; itemLabel: string };
+
+export interface SettingsPanelProps {
+    scope: SdkSettingsScope;
+    /** Caller has `write` on the feature. Render read-only when false. */
+    canWrite: boolean;
+}
+
+export interface FeatureViewProps {
+    /** Closes the full view (the popup over the grid). */
+    closeFeature(): void;
+}
+
+/**
+ * Your package's `./client` export.
+ */
+export interface FeatureClient {
+    /**
+     * The card body on the home grid. NO props, like every native widget:
+     * data comes from `useResource`, so the card and the full view share one
+     * cache and refresh together.
+     */
+    Widget: ComponentType;
+    /** The full view, opened when the card expands. */
+    Full: ComponentType<FeatureViewProps>;
+    /**
+     * Panels for the manifest's settings tabs that need one: `'general'`,
+     * `'sources'`, and any custom tab id. Generic tabs (`'notifications'`,
+     * `'permissions'`) need no panel.
+     */
+    settingsPanels?: Readonly<Record<string, ComponentType<SettingsPanelProps>>>;
+    /**
+     * The compact topbar widget declared by `manifest.topbarWidget`.
+     *
+     * Rendered with NO props, on purpose: that is the security contract. The
+     * host hands the component nothing (no user, no stores, no other feature's
+     * state); everything it shows must come through YOUR feature's commands
+     * (`featureApi`), which the server authorizes against the caller's grants
+     * like any other call. The host also only mounts it for members whose role
+     * grants your feature. Freedom inside the box, nothing outside it.
+     */
+    TopbarWidget?: ComponentType;
+    /**
+     * Minutes the full view stays mounted (state preserved) after closing.
+     * `0` = unmount immediately; omit = mounted forever.
+     */
+    cacheDurationMinutes?: number;
+    /** Warm the full view at idle after load, when the card is placed. */
+    preload?: boolean;
+    /** Hold the password-encryption unlock alive while the full view is open. */
+    holdSecrecy?: boolean;
+}

package/src/sdk/ids.ts

@@ -0,0 +1,25 @@
+/**
+ * Feature ids, re-exported for SDK consumers.
+ *
+ * DevEye has two id families sharing one namespace:
+ *  - the sixteen **native** feature ids, a closed enum (`WorkspaceFeatureId`);
+ *  - **external** module ids, `x-<slug>` strings matching
+ *    {@link EXTERNAL_FEATURE_ID_PATTERN}.
+ *
+ * The `x-` prefix guarantees, by construction, that an external id can never
+ * collide with a native feature, a reserved live topic, or a device UUID in a
+ * home layout. Your module's id is also its command prefix (`x-crypto.list`)
+ * and its live topic.
+ */
+export {
+    EXTERNAL_FEATURE_ID_PATTERN,
+    externalFeatureIdSchema,
+    featureIdSchema,
+    isExternalFeatureId,
+    workspaceFeatureIdSchema,
+    type ExternalFeatureId,
+    type FeatureId,
+    type WorkspaceFeatureId
+} from '../domain/workspaceRole';
+
+export { featureAccessSchema, type FeatureAccess } from '../domain/workspaceRole';

package/src/sdk/index.ts

@@ -0,0 +1,11 @@
+/**
+ * The DevEye feature SDK, shared surface: ids and the manifest contract.
+ *
+ * Side-specific surfaces live in their own entries so neither bundle drags the
+ * other's world in: `deveye-types/sdk/server` (handlers, storage, facade),
+ * `deveye-types/sdk/client` (component contracts), `deveye-types/sdk/testing`
+ * (handler test harness).
+ */
+export * from './ids';
+export * from './manifest';
+export * from './providers';