Add shared package: types, schemas, plans and API client

Holds everything web, mobile and API must agree on: DTOs, zod input
schemas, plan entitlements (the single place feature gates live),
streaming-service link helpers, feed ordering and a typed API client.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MzFywujuH9TiuXbr9vjoX8

packages/shared/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@musicshare/shared",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc -p ."
+  },
+  "dependencies": {
+    "zod": "^4.6.5"
+  }
+}

packages/shared/src/client.ts

@@ -0,0 +1,86 @@
+import type {
+  ConnectionDTO,
+  FeedItemDTO,
+  MeDTO,
+  ProfileDTO,
+  TrackSearchResultDTO,
+  UserSummaryDTO,
+} from './dto';
+import type { LoginInput, RegisterInput, SetFeaturedInput, UpdateMeInput } from './schemas';
+
+export class ApiError extends Error {
+  constructor(
+    public status: number,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+export interface ApiClientOptions {
+  baseUrl: string;
+  /** Bearer token (mobile). Web relies on the session cookie instead. */
+  getToken?: () => string | null | undefined;
+  /** 'include' for browsers talking to the API cross-origin. */
+  credentials?: 'include' | 'same-origin' | 'omit';
+}
+
+export type AuthResponse = { user: MeDTO; token: string };
+
+/** Typed client for the musicshare API, shared by web and mobile. */
+export function createApiClient({ baseUrl, getToken, credentials }: ApiClientOptions) {
+  async function request<T>(path: string, init: { method?: string; body?: unknown } = {}): Promise<T> {
+    const headers: Record<string, string> = {};
+    const token = getToken?.();
+    if (token) headers.Authorization = `Bearer ${token}`;
+    if (init.body !== undefined) headers['Content-Type'] = 'application/json';
+    const res = await fetch(baseUrl + path, {
+      method: init.method ?? (init.body !== undefined ? 'POST' : 'GET'),
+      headers,
+      credentials,
+      body: init.body !== undefined ? JSON.stringify(init.body) : undefined,
+    });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok) throw new ApiError(res.status, (data as { error?: string }).error ?? `Request failed (${res.status})`);
+    return data as T;
+  }
+
+  const q = encodeURIComponent;
+
+  return {
+    request,
+    /** For SWR-style fetchers keyed by path. */
+    get: <T>(path: string) => request<T>(path),
+
+    register: (input: RegisterInput) => request<AuthResponse>('/auth/register', { body: input }),
+    login: (input: LoginInput) => request<AuthResponse>('/auth/login', { body: input }),
+    logout: () => request('/auth/logout', { method: 'POST', body: {} }),
+
+    me: () => request<MeDTO>('/me'),
+    updateMe: (input: UpdateMeInput) => request<MeDTO>('/me', { method: 'PATCH', body: input }),
+    deleteAccount: () => request('/me', { method: 'DELETE' }),
+    setFeatured: (input: SetFeaturedInput) => request('/me/featured', { method: 'PUT', body: input }),
+    clearFeatured: () => request('/me/featured', { method: 'DELETE' }),
+
+    feed: () => request<FeedItemDTO[]>('/feed'),
+    profile: (username: string) => request<ProfileDTO>(`/users/${q(username)}`),
+    searchUsers: (query: string) => request<UserSummaryDTO[]>(`/users/search?q=${q(query)}`),
+    follow: (username: string) => request(`/users/${q(username)}/follow`, { method: 'POST', body: {} }),
+    unfollow: (username: string) => request(`/users/${q(username)}/follow`, { method: 'DELETE' }),
+    pin: (username: string) => request(`/users/${q(username)}/pin`, { method: 'PUT', body: {} }),
+    unpin: (username: string) => request(`/users/${q(username)}/pin`, { method: 'DELETE' }),
+
+    searchTracks: (query: string) => request<TrackSearchResultDTO[]>(`/tracks/search?q=${q(query)}`),
+
+    connections: () => request<ConnectionDTO[]>('/connections'),
+    authorizeUrl: (provider: 'spotify' | 'plex', body: { client: 'web' | 'mobile'; returnTo?: string }) =>
+      request<{ url: string }>(`/connections/${provider}/authorize`, { body }),
+    connectUsername: (provider: 'lastfm' | 'listenbrainz', username: string) =>
+      request<ConnectionDTO>(`/connections/${provider}`, { body: { username } }),
+    connectJellyfin: (input: { serverUrl: string; username: string; password: string }) =>
+      request<ConnectionDTO>('/connections/jellyfin', { body: input }),
+    disconnect: (provider: string) => request(`/connections/${q(provider)}`, { method: 'DELETE' }),
+  };
+}
+
+export type ApiClient = ReturnType<typeof createApiClient>;

packages/shared/src/dto.ts

@@ -0,0 +1,93 @@
+import type { Entitlements, Plan } from './plans';
+import type { NowPlayingProvider, StreamingService } from './services';
+
+export interface TrackDTO {
+  id: string;
+  title: string;
+  artist: string;
+  album: string | null;
+  artworkUrl: string | null;
+  durationMs: number | null;
+  isrc: string | null;
+  links: Partial<Record<StreamingService, string>>;
+}
+
+export interface UserSummaryDTO {
+  id: string;
+  username: string;
+  displayName: string | null;
+  avatarUrl: string | null;
+}
+
+export interface MeDTO extends UserSummaryDTO {
+  email: string;
+  bio: string | null;
+  preferredService: StreamingService | null;
+  plan: Plan;
+  entitlements: Entitlements;
+}
+
+export interface NowPlayingDTO {
+  user: UserSummaryDTO;
+  track: TrackDTO;
+  isPlaying: boolean;
+  source: NowPlayingProvider;
+  progressMs: number | null;
+  updatedAt: string;
+}
+
+/** A feed entry. pinnedAt is set when the viewer pinned this friend. */
+export interface FeedItemDTO extends NowPlayingDTO {
+  pinnedAt: string | null;
+}
+
+/** Pinned first (oldest pin on top, so order is stable), then live listeners, then most recent. */
+export function sortFeed<T extends FeedItemDTO>(items: T[]): T[] {
+  return [...items].sort(
+    (a, b) =>
+      Number(Boolean(b.pinnedAt)) - Number(Boolean(a.pinnedAt)) ||
+      (a.pinnedAt && b.pinnedAt ? a.pinnedAt.localeCompare(b.pinnedAt) : 0) ||
+      Number(b.isPlaying) - Number(a.isPlaying) ||
+      b.updatedAt.localeCompare(a.updatedAt),
+  );
+}
+
+export interface FeaturedSongDTO {
+  track: TrackDTO;
+  comment: string | null;
+  updatedAt: string;
+}
+
+export interface ProfileDTO {
+  user: UserSummaryDTO & { bio: string | null };
+  followerCount: number;
+  followingCount: number;
+  isFollowing: boolean;
+  isPinned: boolean;
+  isSelf: boolean;
+  featured: FeaturedSongDTO | null;
+  nowPlaying: NowPlayingDTO | null;
+}
+
+export interface ConnectionDTO {
+  provider: NowPlayingProvider;
+  externalUserId: string;
+  displayName: string | null;
+  status: 'active' | 'error';
+  lastError: string | null;
+  lastPolledAt: string | null;
+  /** Secret URL the user can paste into Plex/Jellyfin for instant updates. */
+  webhookUrl: string | null;
+}
+
+export interface TrackSearchResultDTO {
+  deezerId: string;
+  title: string;
+  artist: string;
+  album: string | null;
+  artworkUrl: string | null;
+  durationMs: number | null;
+}
+
+/** Messages pushed over the realtime websocket. */
+export type RealtimeMessage = { type: 'now_playing'; data: NowPlayingDTO };

packages/shared/src/index.ts

@@ -0,0 +1,6 @@
+export * from './services';
+export * from './dto';
+export * from './schemas';
+export * from './plans';
+export * from './client';
+export * from './time';

packages/shared/src/plans.ts

@@ -0,0 +1,22 @@
+export const PLANS = ['free', 'plus'] as const;
+export type Plan = (typeof PLANS)[number];
+
+/**
+ * Every feature gate lives here so paid tiers can be reshaped without
+ * hunting through the codebase. Clients read these to show upsells.
+ */
+export interface Entitlements {
+  /** How often we refresh now-playing while someone is watching you. */
+  activePollSeconds: number;
+  maxConnections: number;
+  /** Friends you can pin to the top of your feed. */
+  maxPinnedFriends: number;
+  /** Placeholder for future paid features. */
+  listeningHistory: boolean;
+  profileThemes: boolean;
+}
+
+export const PLAN_ENTITLEMENTS: Record<Plan, Entitlements> = {
+  free: { activePollSeconds: 15, maxConnections: 3, maxPinnedFriends: 3, listeningHistory: false, profileThemes: false },
+  plus: { activePollSeconds: 5, maxConnections: 10, maxPinnedFriends: 20, listeningHistory: true, profileThemes: true },
+};

packages/shared/src/schemas.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+import { STREAMING_SERVICES } from './services';
+
+export const usernameSchema = z
+  .string()
+  .trim()
+  .toLowerCase()
+  .regex(/^[a-z0-9_]{3,32}$/, 'Username must be 3-32 characters: letters, numbers, underscores');
+
+export const registerSchema = z.object({
+  username: usernameSchema,
+  email: z.email().trim().toLowerCase(),
+  password: z.string().min(8, 'Password must be at least 8 characters').max(200),
+});
+
+export const loginSchema = z.object({
+  email: z.email().trim().toLowerCase(),
+  password: z.string().min(1).max(200),
+});
+
+export const updateMeSchema = z.object({
+  displayName: z.string().trim().max(64).nullable().optional(),
+  bio: z.string().trim().max(280).nullable().optional(),
+  avatarUrl: z.url().max(500).nullable().optional(),
+  preferredService: z.enum(STREAMING_SERVICES).nullable().optional(),
+});
+
+export const setFeaturedSchema = z.union([
+  z.object({ deezerId: z.string().regex(/^\d+$/), comment: z.string().trim().max(280).nullable().optional() }),
+  z.object({ trackId: z.uuid(), comment: z.string().trim().max(280).nullable().optional() }),
+]);
+
+export const connectUsernameSchema = z.object({
+  username: z.string().trim().min(1).max(64),
+});
+
+export type RegisterInput = z.infer<typeof registerSchema>;
+export type LoginInput = z.infer<typeof loginSchema>;
+export type UpdateMeInput = z.infer<typeof updateMeSchema>;
+export type SetFeaturedInput = z.infer<typeof setFeaturedSchema>;
+
+export const jellyfinConnectSchema = z.object({
+  serverUrl: z.string().trim().min(1).max(500),
+  username: z.string().trim().min(1).max(128),
+  password: z.string().max(256).default(''),
+});

packages/shared/src/services.ts

@@ -0,0 +1,64 @@
+/** Services a listener can open a song in. */
+export const STREAMING_SERVICES = [
+  'spotify',
+  'apple_music',
+  'youtube_music',
+  'deezer',
+  'tidal',
+] as const;
+export type StreamingService = (typeof STREAMING_SERVICES)[number];
+
+/** Sources we can read "now playing" from. */
+export const NOW_PLAYING_PROVIDERS = [
+  'spotify',
+  'lastfm',
+  'listenbrainz',
+  'plex',
+  'jellyfin',
+  'apple_music',
+  'android_media_session',
+] as const;
+export type NowPlayingProvider = (typeof NOW_PLAYING_PROVIDERS)[number];
+
+export const SERVICE_LABELS: Record<StreamingService | NowPlayingProvider, string> = {
+  spotify: 'Spotify',
+  apple_music: 'Apple Music',
+  youtube_music: 'YouTube Music',
+  deezer: 'Deezer',
+  tidal: 'TIDAL',
+  lastfm: 'Last.fm',
+  listenbrainz: 'ListenBrainz',
+  plex: 'Plex',
+  jellyfin: 'Jellyfin',
+  android_media_session: 'Android',
+};
+
+/** Fallback when we have no direct link: a search on that service. */
+export function searchUrl(service: StreamingService, title: string, artist: string): string {
+  const q = encodeURIComponent(`${artist} ${title}`);
+  switch (service) {
+    case 'spotify':
+      return `https://open.spotify.com/search/${q}`;
+    case 'apple_music':
+      return `https://music.apple.com/search?term=${q}`;
+    case 'youtube_music':
+      return `https://music.youtube.com/search?q=${q}`;
+    case 'deezer':
+      return `https://www.deezer.com/search/${q}`;
+    case 'tidal':
+      return `https://listen.tidal.com/search?q=${q}`;
+  }
+}
+
+/**
+ * The URL to open a track in the given service. All direct links are https
+ * universal/app links, so they open the native app when installed.
+ */
+export function openUrl(
+  track: { title: string; artist: string; links: Partial<Record<StreamingService, string>> },
+  service: StreamingService,
+): { url: string; exact: boolean } {
+  const direct = track.links[service];
+  if (direct) return { url: direct, exact: true };
+  return { url: searchUrl(service, track.title, track.artist), exact: false };
+}

packages/shared/src/time.ts

@@ -0,0 +1,7 @@
+export function timeAgo(iso: string): string {
+  const s = Math.max(0, (Date.now() - new Date(iso).getTime()) / 1000);
+  if (s < 60) return 'just now';
+  if (s < 3600) return `${Math.floor(s / 60)}m ago`;
+  if (s < 86400) return `${Math.floor(s / 3600)}h ago`;
+  return `${Math.floor(s / 86400)}d ago`;
+}

packages/shared/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "include": [
+    "src"
+  ],
+  "compilerOptions": {
+    "lib": [
+      "ES2023",
+      "DOM"
+    ]
+  }
+}