@slidev-polls/shared 0.0.1

package/README.md

@@ -0,0 +1,29 @@
+# @slidev-polls/shared
+
+Shared TypeScript types, REST/SSE clients, and Vue UI primitives consumed by
+the [slidev-polls](https://github.com/asm0dey/slidev-polls) suite (Slidev
+addon, voter SPA, backoffice SPA).
+
+Ships untranspiled `.ts` and `.vue` source. Intended for projects that build
+with Vite or another bundler that understands TypeScript and Vue SFCs.
+
+## Install
+
+```bash
+npm install @slidev-polls/shared
+# or
+bun add @slidev-polls/shared
+```
+
+`vue@^3.5` is a peer dependency.
+
+## Exports
+
+- `@slidev-polls/shared` — types, `apiClient`, `sseClient`
+- `@slidev-polls/shared/ui` — Vue UI components (`ResultsPanel`,
+  `AllowedOriginsField`, theme helpers)
+- `@slidev-polls/shared/tokens.css` — CSS design tokens
+
+## License
+
+GPL-3.0-or-later. See [LICENSE](./LICENSE).

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@slidev-polls/shared",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Shared types, API client, SSE client, and Vue UI primitives for the slidev-polls suite.",
+  "license": "GPL-3.0-or-later",
+  "author": "Pasha Finkelshteyn <pavel.finkelshtein@gmail.com>",
+  "homepage": "https://github.com/asm0dey/slidev-polls#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/asm0dey/slidev-polls.git",
+    "directory": "frontends/shared"
+  },
+  "bugs": {
+    "url": "https://github.com/asm0dey/slidev-polls/issues"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./ui": "./src/ui/index.ts",
+    "./tokens.css": "./src/ui/tokens.css"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "bun run test && bun run build"
+  },
+  "peerDependencies": {
+    "vue": "^3.5.0"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^6.0.6",
+    "@vue/test-utils": "^2.4.10",
+    "jsdom": "^29.1.1",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.11",
+    "vitest": "^4.1.5",
+    "vue": "^3.5.34"
+  }
+}

package/src/api-client.ts

@@ -0,0 +1,105 @@
+import type { Problem, ProblemCode, PublicPollView, VoteAccepted, VoteRequest } from "./types";
+
+export interface ApiClientOptions {
+  baseUrl?: string;
+  /** Optional injection point for tests. */
+  fetchImpl?: typeof fetch;
+}
+
+/**
+ * Thrown by {@link ApiClient} on any non-2xx response. Carries the parsed
+ * {@link Problem} envelope so callers can branch on a typed {@code code}
+ * rather than scraping HTTP status codes.
+ */
+export class ApiError extends Error {
+  readonly status: number;
+  readonly problem: Problem | null;
+
+  constructor(status: number, problem: Problem | null, message: string) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    this.problem = problem;
+  }
+
+  get code(): ProblemCode | undefined {
+    return this.problem?.code;
+  }
+
+  get correlationId(): string | undefined {
+    return this.problem?.correlationId ?? undefined;
+  }
+}
+
+export class ApiClient {
+  private readonly baseUrl: string;
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(opts: ApiClientOptions = {}) {
+    this.baseUrl = (opts.baseUrl ?? "").replace(/\/$/, "");
+    // Browsers require window.fetch to be called with `this === window`. When we
+    // store the global `fetch` on an instance and later invoke it as
+    // `this.fetchImpl(…)`, the receiver becomes the ApiClient and Chrome rejects
+    // the call with "Failed to execute 'fetch' on 'Window': Illegal invocation"
+    // (surfaced by BUG-005). Binding to globalThis keeps the call site simple
+    // while preserving the test injection hook.
+    this.fetchImpl = opts.fetchImpl ?? fetch.bind(globalThis);
+  }
+
+  async publicPoll(slug: string): Promise<PublicPollView> {
+    const res = await this.fetchImpl(
+      `${this.baseUrl}/api/polls/by-slug/${encodeURIComponent(slug)}`,
+      { credentials: "same-origin" }
+    );
+    if (!res.ok) {
+      throw await toApiError(res);
+    }
+    return (await res.json()) as PublicPollView;
+  }
+
+  async submitVote(slug: string, body: VoteRequest): Promise<VoteAccepted | null> {
+    const res = await this.fetchImpl(
+      `${this.baseUrl}/api/polls/${encodeURIComponent(slug)}/votes`,
+      {
+        method: "POST",
+        credentials: "same-origin",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body)
+      }
+    );
+    if (!res.ok) {
+      throw await toApiError(res);
+    }
+    // The 201 body is VoteAccepted; 204 is tolerated for back-compat.
+    if (res.status === 204) {
+      return null;
+    }
+    return (await res.json()) as VoteAccepted;
+  }
+}
+
+/**
+ * Parses a Problem envelope from a non-2xx response. The server always returns
+ * application/json for API failures, but fall back to a plain message if the
+ * body cannot be decoded (e.g., a gateway injected an HTML error page) so the
+ * caller still gets a meaningful error.
+ */
+async function toApiError(res: Response): Promise<ApiError> {
+  const contentType = res.headers.get("content-type") ?? "";
+  if (contentType.includes("application/json")) {
+    try {
+      const body = (await res.json()) as Partial<Problem>;
+      if (body && typeof body.code === "string" && typeof body.message === "string") {
+        const problem: Problem = {
+          code: body.code as ProblemCode,
+          message: body.message,
+          correlationId: body.correlationId
+        };
+        return new ApiError(res.status, problem, problem.message);
+      }
+    } catch {
+      // fall through
+    }
+  }
+  return new ApiError(res.status, null, `HTTP ${res.status}`);
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./types";
+export * from "./api-client";
+export * from "./sse-client";
+export * from "./ui";

package/src/shims-vue.d.ts

@@ -0,0 +1,5 @@
+declare module "*.vue" {
+  import type { DefineComponent } from "vue";
+  const component: DefineComponent<object, object, unknown>;
+  export default component;
+}

package/src/sse-client.ts

@@ -0,0 +1,118 @@
+import type { QuestionClosedEvent, SnapshotEvent, TallyDeltaEvent } from "./types";
+
+export interface StreamHandlers {
+  onSnapshot: (ev: SnapshotEvent) => void;
+  onTally: (ev: TallyDeltaEvent) => void;
+  onQuestionClosed?: (ev: QuestionClosedEvent) => void;
+  onConnectionStateChange?: (state: "open" | "paused") => void;
+}
+
+/** Factory that produces an {@link EventSource} for a given URL. Overridable in tests. */
+export type EventSourceFactory = (url: string) => EventSource;
+
+/** Schedules {@code fn} to run after {@code ms} milliseconds; returns a cancel handle. */
+export type DelayedScheduler = (fn: () => void, ms: number) => () => void;
+
+export interface OpenPollStreamOptions {
+  eventSourceFactory?: EventSourceFactory;
+  scheduler?: DelayedScheduler;
+  /** Delay for the first reconnect attempt after an error. Defaults to 500ms. */
+  minDelayMs?: number;
+  /** Ceiling for the exponentially-growing reconnect delay. Defaults to 10s. */
+  maxDelayMs?: number;
+}
+
+const DEFAULT_MIN_DELAY_MS = 500;
+const DEFAULT_MAX_DELAY_MS = 10_000;
+
+const defaultEventSourceFactory: EventSourceFactory = (url) =>
+  new EventSource(url, { withCredentials: true });
+
+const defaultScheduler: DelayedScheduler = (fn, ms) => {
+  const id = setTimeout(fn, ms);
+  return () => clearTimeout(id);
+};
+
+/**
+ * Subscribe to the SSE stream for a single poll. The returned callback
+ * unsubscribes and also cancels any pending reconnect, so callers do not have
+ * to track timers themselves.
+ *
+ * <p>On connection failure the client flips the state to {@code "paused"},
+ * closes the broken {@link EventSource}, and schedules a reconnect with
+ * exponential backoff starting at {@code minDelayMs} and capped at
+ * {@code maxDelayMs}. A successful {@code open} event resets the backoff so a
+ * later failure starts over at {@code minDelayMs}.
+ *
+ * <p>This matches Principle IV (Live-Reliability Over Feature Depth): the UI
+ * shows a visible "paused" badge during reconnect rather than throwing, and
+ * the backoff cap keeps a long outage from blowing up to minute-long retries.
+ */
+export function openPollStream(
+  baseUrl: string,
+  slug: string,
+  handlers: StreamHandlers,
+  opts: OpenPollStreamOptions = {}
+): () => void {
+  const url = `${baseUrl.replace(/\/$/, "")}/api/polls/${encodeURIComponent(slug)}/stream`;
+  const esFactory = opts.eventSourceFactory ?? defaultEventSourceFactory;
+  const schedule = opts.scheduler ?? defaultScheduler;
+  const minDelay = opts.minDelayMs ?? DEFAULT_MIN_DELAY_MS;
+  const maxDelay = opts.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+
+  let currentEs: EventSource | null = null;
+  let cancelRetry: (() => void) | null = null;
+  let retryDelay = minDelay;
+  let stopped = false;
+
+  function connect() {
+    if (stopped) {
+      return;
+    }
+    const es = esFactory(url);
+    currentEs = es;
+
+    es.addEventListener("open", () => {
+      retryDelay = minDelay;
+      handlers.onConnectionStateChange?.("open");
+    });
+
+    es.addEventListener("error", () => {
+      handlers.onConnectionStateChange?.("paused");
+      es.close();
+      if (currentEs === es) {
+        currentEs = null;
+      }
+      const scheduledDelay = retryDelay;
+      retryDelay = Math.min(retryDelay * 2, maxDelay);
+      cancelRetry = schedule(() => {
+        cancelRetry = null;
+        connect();
+      }, scheduledDelay);
+    });
+
+    es.addEventListener("snapshot", (e) => {
+      handlers.onSnapshot(JSON.parse((e as MessageEvent).data) as SnapshotEvent);
+    });
+    es.addEventListener("tally", (e) => {
+      handlers.onTally(JSON.parse((e as MessageEvent).data) as TallyDeltaEvent);
+    });
+    es.addEventListener("question-closed", (e) => {
+      handlers.onQuestionClosed?.(JSON.parse((e as MessageEvent).data) as QuestionClosedEvent);
+    });
+  }
+
+  connect();
+
+  return () => {
+    stopped = true;
+    if (cancelRetry) {
+      cancelRetry();
+      cancelRetry = null;
+    }
+    if (currentEs) {
+      currentEs.close();
+      currentEs = null;
+    }
+  };
+}

package/src/types.ts

@@ -0,0 +1,195 @@
+// Mirrors the schemas in specs/001-polling-foundation/contracts/openapi.yaml.
+// Keep this file and the OpenAPI document in lock-step so the voter, backoffice,
+// and slidev-addon packages all speak the same DTOs.
+
+export type PollStatus = "DRAFT" | "OPEN" | "CLOSED";
+export type QuestionStatus = "DRAFT" | "ACTIVE" | "CLOSED";
+
+export interface PollStyle {
+  primaryColor?: string;
+  accentColor?: string;
+  backgroundColor?: string;
+  fontFamily?: string;
+  layout?: "BARS" | "COLUMNS" | "DONUT";
+}
+
+export interface Option {
+  id: string;
+  label: string;
+  position: number;
+}
+
+export interface Question {
+  id: string;
+  prompt: string;
+  ordinal: number;
+  status: QuestionStatus;
+  options: Option[];
+}
+
+/** Back-compat alias for callers that imported `PollOption`; prefer `Option`. */
+export type PollOption = Option;
+
+/** Backoffice-side poll summary (GET /api/admin/polls). */
+export interface Poll {
+  id: string;
+  title: string;
+  slug: string;
+  status: PollStatus;
+  publicUrl: string;
+  activeQuestionId: string | null;
+}
+
+/** Full poll with questions, options, and style (GET /api/admin/polls/{id}). */
+export interface PollDetail extends Poll {
+  style: PollStyle;
+  questions: Question[];
+  allowedOrigins?: string[];
+}
+
+/** Public-facing poll view (GET /api/polls/by-slug/{slug}). */
+export interface PublicPollView {
+  pollId: string;
+  slug: string;
+  title: string;
+  state: "WAITING" | "ACTIVE";
+  style: PollStyle;
+  activeQuestion?: Question;
+  alreadyVoted?: boolean;
+}
+
+/** Login payload (POST /api/admin/login). */
+export interface LoginRequest {
+  username: string;
+  password: string;
+}
+
+/** Option payload inside CreateQuestionRequest. */
+export interface CreateOptionRequest {
+  label: string;
+}
+
+/** Question payload for create/update (POST /api/admin/polls). */
+export interface CreateQuestionRequest {
+  prompt: string;
+  options: CreateOptionRequest[];
+}
+
+/** Create-poll payload (POST /api/admin/polls). */
+export interface CreatePollRequest {
+  title: string;
+  slug?: string;
+  style?: PollStyle;
+  questions: CreateQuestionRequest[];
+  allowedOrigins?: string[];
+}
+
+/** Patch-style update payload (PATCH /api/admin/polls/{id}). */
+export interface UpdatePollRequest {
+  title?: string;
+  slug?: string;
+  questions?: CreateQuestionRequest[];
+  allowedOrigins?: string[];
+}
+
+/** Activate-question payload (POST /api/admin/polls/{id}/open). */
+export interface ActivateQuestionRequest {
+  questionId: string;
+}
+
+/** Vote submission payload (POST /api/polls/{slug}/votes). */
+export interface VoteRequest {
+  optionId: string;
+  voterToken: string;
+}
+
+/** Vote accepted response. */
+export interface VoteAccepted {
+  voteId: string;
+  /** ISO-8601 timestamp at which the vote was persisted. */
+  recordedAt: string;
+}
+
+/** OpenAPI Problem error envelope. */
+export type ProblemCode =
+  | "AUTH_REQUIRED"
+  | "FORBIDDEN"
+  | "NOT_FOUND"
+  | "VALIDATION_FAILED"
+  | "ALREADY_VOTED"
+  | "QUESTION_NOT_ACTIVE"
+  | "ACTIVATION_REJECTED"
+  | "SLUG_TAKEN"
+  | "SLUG_INVALID"
+  | "SLUG_RESERVED"
+  | "DECK_TOKEN_INVALID"
+  | "DECK_TOKEN_POLL_MISMATCH"
+  | "ORIGIN_INVALID"
+  | "SETUP_LOCKED"
+  | "USERNAME_TAKEN"
+  | "TRANSPORT_FAILURE";
+
+export interface Problem {
+  code: ProblemCode;
+  message: string;
+  correlationId?: string;
+  /** Per-field validation messages, populated only on VALIDATION_FAILED. */
+  errors?: Record<string, string[]>;
+}
+
+/** Deck token as listed in the backoffice (GET /api/admin/polls/{id}/deck-tokens). */
+export interface DeckToken {
+  id: string;
+  pollId: string;
+  label: string | null;
+  createdAt: string;
+  revokedAt: string | null;
+}
+
+/** Freshly minted deck token — plaintext bearer returned once (POST .../deck-tokens). */
+export interface DeckTokenMinted extends DeckToken {
+  plaintext: string;
+}
+
+export interface MintDeckTokenRequest {
+  label?: string | null;
+}
+
+/** Slimmed snapshot of an active question — what the SSE `snapshot` event carries.
+ *  Lacks `status` because the SSE stream is only emitted for the currently-active question. */
+export interface SnapshotActiveQuestion {
+  id: string;
+  prompt: string;
+  ordinal: number;
+  options: Option[];
+}
+
+/** SSE "snapshot" event — full state for a poll/question, re-emitted on (re)connect. */
+export interface SnapshotEvent {
+  pollId: string;
+  slug: string;
+  activeQuestion: SnapshotActiveQuestion | null;
+  tally: TallyEntry[];
+  emittedAt: string;
+}
+
+export interface TallyEntry {
+  optionId: string;
+  count: number;
+}
+
+/** SSE "tally" event — delta for a single option, fan-out on each accepted vote. */
+export interface TallyDeltaEvent {
+  pollId: string;
+  questionId: string;
+  optionId: string;
+  count: number;
+  emittedAt: string;
+}
+
+/** SSE "question-closed" event. */
+export interface QuestionClosedEvent {
+  pollId: string;
+  questionId: string;
+  emittedAt: string;
+}

package/src/ui/AllowedOriginsField.vue

@@ -0,0 +1,116 @@
+<script setup lang="ts">
+import { computed, ref } from "vue";
+import Chip from "./Chip.vue";
+import IconAlert from "./IconAlert.vue";
+import { validateOrigin } from "./origin-validator";
+
+const props = defineProps<{ modelValue: string[] }>();
+const emit = defineEmits<{ "update:modelValue": [v: string[]] }>();
+
+const draft = ref("");
+const error = ref<string | null>(null);
+
+const items = computed(() =>
+  props.modelValue.map((o) => {
+    const r = validateOrigin(o);
+    return { raw: o, invalid: !r.ok };
+  })
+);
+
+function commit() {
+  const v = draft.value;
+  if (!v.trim()) {
+    error.value = null;
+    return;
+  }
+  const r = validateOrigin(v);
+  if (!r.ok) {
+    error.value = r.message;
+    return;
+  }
+  if (props.modelValue.includes(r.normalized)) {
+    error.value = `Already added`;
+    return;
+  }
+  emit("update:modelValue", [...props.modelValue, r.normalized]);
+  draft.value = "";
+  error.value = null;
+}
+
+function remove(idx: number) {
+  const next = props.modelValue.slice();
+  next.splice(idx, 1);
+  emit("update:modelValue", next);
+}
+</script>
+
+<template>
+  <div class="sp-aof">
+    <div class="sp-aof-box">
+      <Chip
+        v-for="(item, i) in items"
+        :key="i"
+        :label="item.raw"
+        :invalid="item.invalid"
+        :mono="true"
+        data-testid="origin-chip"
+        @remove="remove(i)"
+      >
+        <template v-if="item.invalid" #leading>
+          <IconAlert />
+        </template>
+      </Chip>
+      <input
+        v-model="draft"
+        class="sp-aof-input"
+        placeholder="https://… (Enter or Tab to add)"
+        @keydown.enter.prevent="commit"
+        @blur="commit"
+      />
+    </div>
+    <div v-if="error" class="sp-aof-error" data-testid="aof-error" role="alert">
+      <IconAlert />
+      <span>{{ error }}</span>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.sp-aof {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+.sp-aof-box {
+  border: 1px solid var(--sp-border);
+  border-radius: var(--sp-radius);
+  padding: 8px;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  min-height: 42px;
+  background: var(--sp-bg);
+}
+.sp-aof-input {
+  flex: 1;
+  min-width: 160px;
+  border: 0;
+  outline: 0;
+  background: transparent;
+  font-size: 13px;
+  font-family: var(--sp-font-mono);
+  padding: 4px 6px;
+  color: var(--sp-fg);
+}
+.sp-aof-error {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 8px 10px;
+  background: var(--sp-danger-bg);
+  border: 1px solid var(--sp-danger);
+  border-radius: var(--sp-radius-sm);
+  font-size: 12px;
+  color: var(--sp-danger-fg);
+}
+</style>

package/src/ui/Button.vue

@@ -0,0 +1,77 @@
+<script setup lang="ts">
+withDefaults(
+  defineProps<{
+    variant?: "primary" | "secondary" | "ghost" | "danger";
+    size?: "sm" | "md";
+    type?: "button" | "submit" | "reset";
+  }>(),
+  { variant: "primary", size: "md", type: "button" }
+);
+</script>
+
+<template>
+  <button :type="type" :data-variant="variant" :data-size="size" class="sp-btn">
+    <slot />
+  </button>
+</template>
+
+<style scoped>
+.sp-btn {
+  font-family: var(--sp-font-sans);
+  font-weight: 500;
+  border-radius: var(--sp-radius);
+  border: 1px solid transparent;
+  cursor: pointer;
+  transition:
+    background var(--sp-dur) var(--sp-ease),
+    border-color var(--sp-dur) var(--sp-ease);
+  white-space: nowrap;
+}
+.sp-btn[data-size="md"] {
+  padding: 11px 14px;
+  font-size: 14px;
+}
+.sp-btn[data-size="sm"] {
+  padding: 7px 12px;
+  font-size: 12px;
+}
+
+.sp-btn[data-variant="primary"] {
+  background: var(--sp-fg);
+  color: var(--sp-bg);
+}
+.sp-btn[data-variant="primary"]:hover {
+  opacity: 0.9;
+}
+
+.sp-btn[data-variant="secondary"] {
+  background: var(--sp-bg);
+  color: var(--sp-fg);
+  border-color: var(--sp-border);
+}
+.sp-btn[data-variant="secondary"]:hover {
+  background: var(--sp-bg-muted);
+}
+
+.sp-btn[data-variant="ghost"] {
+  background: transparent;
+  color: var(--sp-fg-muted);
+}
+.sp-btn[data-variant="ghost"]:hover {
+  background: var(--sp-bg-muted);
+}
+
+.sp-btn[data-variant="danger"] {
+  background: var(--sp-danger);
+  color: #fff;
+}
+
+.sp-btn:focus-visible {
+  outline: 2px solid var(--sp-accent-ring);
+  outline-offset: 2px;
+}
+.sp-btn:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+</style>