@venue-family/sdk 1.0.0

package/dist/webhooks.d.ts

@@ -0,0 +1,21 @@
+import type { VenueFamilyEmbedEvent } from './types.js';
+/**
+ * Verify an incoming Venue Family webhook or conversion postback HMAC-SHA256 signature.
+ * Works in Node.js, Deno, Bun, and Web standard runtimes (Cloudflare Workers, Browsers).
+ */
+export declare function verifyWebhookSignature(payload: string, signatureHeader: string, secret: string): Promise<boolean>;
+export interface EmbedListenerOptions {
+    allowedOrigin?: string;
+    onResize?: (height: number) => void;
+    onTicketPurchase?: (event: Extract<VenueFamilyEmbedEvent, {
+        type: 'ticket-purchase-complete';
+    }>) => void;
+    onFormSubmitted?: (event: Extract<VenueFamilyEmbedEvent, {
+        type: 'form-submitted';
+    }>) => void;
+    onEvent?: (event: VenueFamilyEmbedEvent) => void;
+}
+/**
+ * Convenience helper to attach an iframe auto-resize and event listener to any web page.
+ */
+export declare function attachEmbedListener(iframe: HTMLIFrameElement | string, options?: EmbedListenerOptions): () => void;

package/dist/webhooks.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyWebhookSignature = verifyWebhookSignature;
+exports.attachEmbedListener = attachEmbedListener;
+/**
+ * Verify an incoming Venue Family webhook or conversion postback HMAC-SHA256 signature.
+ * Works in Node.js, Deno, Bun, and Web standard runtimes (Cloudflare Workers, Browsers).
+ */
+async function verifyWebhookSignature(payload, signatureHeader, secret) {
+    if (!signatureHeader || !secret) {
+        return false;
+    }
+    const expectedPrefix = 'sha256=';
+    const provided = signatureHeader.startsWith(expectedPrefix)
+        ? signatureHeader.slice(expectedPrefix.length)
+        : signatureHeader;
+    // Standard Web Crypto API
+    const encoder = new TextEncoder();
+    const key = await crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const signatureBuffer = await crypto.subtle.sign('HMAC', key, encoder.encode(payload));
+    const hexHash = Array.from(new Uint8Array(signatureBuffer))
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+    return hexHash === provided;
+}
+/**
+ * Convenience helper to attach an iframe auto-resize and event listener to any web page.
+ */
+function attachEmbedListener(iframe, options = {}) {
+    const allowedOrigin = options.allowedOrigin ?? 'https://venuefamily.com';
+    const handler = (event) => {
+        if (allowedOrigin !== '*' && event.origin !== allowedOrigin) {
+            return;
+        }
+        const data = event.data;
+        if (!data || typeof data !== 'object' || !('type' in data)) {
+            return;
+        }
+        const frameEl = typeof iframe === 'string' ? document.getElementById(iframe) : iframe;
+        if (data.type === 'resize' && frameEl && typeof data.height === 'number') {
+            frameEl.style.height = `${data.height}px`;
+            options.onResize?.(data.height);
+        }
+        if (data.type === 'scroll-into-view' && frameEl && typeof data.top === 'number') {
+            const rect = frameEl.getBoundingClientRect();
+            window.scrollTo({
+                top: window.scrollY + rect.top + data.top - 20,
+                behavior: 'smooth',
+            });
+        }
+        if (data.type === 'ticket-purchase-complete') {
+            options.onTicketPurchase?.(data);
+        }
+        if (data.type === 'form-submitted') {
+            options.onFormSubmitted?.(data);
+        }
+        options.onEvent?.(data);
+    };
+    window.addEventListener('message', handler);
+    return () => {
+        window.removeEventListener('message', handler);
+    };
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@venue-family/sdk",
+  "version": "1.0.0",
+  "description": "Official TypeScript & JavaScript SDK for Venue Family API, events, and dynamic embeds.",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run"
+  },
+  "keywords": [
+    "venue-family",
+    "events",
+    "ticketing",
+    "sdk",
+    "typescript",
+    "api"
+  ],
+  "author": "Venue Family Team <support@venuefamily.com>",
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  }
+}

package/src/client.ts

@@ -0,0 +1,275 @@
+import type {
+  EventData,
+  EventDateData,
+  EventsFilterOptions,
+  FormData,
+  FormSignatureData,
+  LocationData,
+  LocationsFilterOptions,
+  ReviewData,
+  RoleData,
+  UserData,
+  VenueFamilyConfig,
+  VolunteerRoleData,
+} from './types.js';
+
+export class VenueFamilyClient {
+  private readonly baseUrl: string;
+  private readonly apiKey?: string;
+  private readonly organization?: string;
+  private readonly customFetch: typeof fetch;
+
+  constructor(config: VenueFamilyConfig = {}) {
+    this.baseUrl = (config.baseUrl ?? 'https://venuefamily.com/api').replace(/\/+$/, '');
+    this.apiKey = config.apiKey;
+    this.organization = config.organization;
+    this.customFetch = config.fetch ?? fetch.bind(globalThis);
+  }
+
+  public forOrganization(organization: string): VenueFamilyClient {
+    return new VenueFamilyClient({
+      baseUrl: this.baseUrl,
+      apiKey: this.apiKey,
+      organization,
+      fetch: this.customFetch,
+    });
+  }
+
+  private getOrgSlug(): string {
+    if (!this.organization) {
+      throw new Error('Organization slug is required. Pass organization in config or use client.forOrganization("slug").');
+    }
+    return this.organization;
+  }
+
+  private async request<T>(path: string, options: RequestInit = {}): Promise<T> {
+    const url = `${this.baseUrl}/${path.replace(/^\/+/, '')}`;
+    const headers: Record<string, string> = {
+      Accept: 'application/json',
+      ...(options.headers as Record<string, string> || {}),
+    };
+
+    if (this.apiKey) {
+      headers['Authorization'] = `Bearer ${this.apiKey}`;
+      headers['X-API-Key'] = this.apiKey;
+    }
+
+    const response = await this.customFetch(url, {
+      ...options,
+      headers,
+    });
+
+    if (!response.ok) {
+      const errorBody = await response.text();
+      let parsed = null;
+      try {
+        parsed = JSON.parse(errorBody);
+      } catch {
+        // use raw body
+      }
+      throw new Error(parsed?.message || parsed?.error || `Venue Family API Error: ${response.status} ${response.statusText}`);
+    }
+
+    return response.json() as Promise<T>;
+  }
+
+  // --- Auth & User Management ---
+
+  public readonly auth = {
+    login: async (email: string, password: string, organizationSlug?: string, deviceName: string = 'TS SDK'): Promise<{ token: string; user: UserData }> => {
+      const body: Record<string, unknown> = { email, password, device_name: deviceName };
+      if (organizationSlug) body.organization_slug = organizationSlug;
+      return this.request('auth/login', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+      });
+    },
+
+    register: async (userData: Record<string, unknown>): Promise<{ token: string; user: UserData }> => {
+      return this.request('auth/register', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(userData),
+      });
+    },
+
+    user: async (): Promise<UserData> => {
+      const res = await this.request<{ user: UserData }>('auth/user');
+      return res.user;
+    },
+
+    updateProfile: async (attributes: Partial<UserData>): Promise<UserData> => {
+      const res = await this.request<{ user: UserData }>('auth/profile', {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(attributes),
+      });
+      return res.user;
+    },
+
+    updatePassword: async (currentPassword: string, password: string, passwordConfirmation: string): Promise<{ message: string }> => {
+      return this.request('auth/password', {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          current_password: currentPassword,
+          password,
+          password_confirmation: passwordConfirmation,
+        }),
+      });
+    },
+
+    logout: async (): Promise<{ message: string }> => {
+      return this.request('auth/logout', { method: 'POST' });
+    },
+  };
+
+  public readonly users = {
+    me: async (): Promise<UserData> => this.auth.user(),
+    updateProfile: async (attributes: Partial<UserData>): Promise<UserData> => this.auth.updateProfile(attributes),
+    myVolunteerRoles: async (): Promise<{ data: VolunteerRoleData[] }> => this.request('volunteer-roles/my-roles'),
+    volunteerOpportunities: async (): Promise<{ data: VolunteerRoleData[] }> => this.request('volunteer-opportunities'),
+    signUpForVolunteerRole: async (roleId: number): Promise<{ success: boolean }> => {
+      return this.request('volunteer-roles/sign-up', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ role_id: roleId }),
+      });
+    },
+  };
+
+  public readonly roles = {
+    all: async (): Promise<{ data: RoleData[] }> => this.request('roles'),
+    find: async (roleIdOrSlug: number | string): Promise<{ data: RoleData }> => this.request(`roles/${roleIdOrSlug}`),
+  };
+
+  public readonly signatures = {
+    find: async (signingToken: string): Promise<{ data: FormSignatureData }> => this.request(`signatures/${signingToken}`),
+    signNative: async (signingToken: string, signatureData: string, name: string, email?: string): Promise<{ success: boolean }> => {
+      return this.request(`signatures/${signingToken}/sign`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          signature_data: signatureData,
+          name,
+          email,
+          mechanism: 'native',
+        }),
+      });
+    },
+    getSigningUrl: (signingToken: string): string => {
+      const rootUrl = this.baseUrl.replace(/\/api\/?$/, '');
+      return `${rootUrl}/forms/countersign/${signingToken}`;
+    },
+  };
+
+  // --- Events ---
+
+  public readonly events = {
+    all: async (filters: EventsFilterOptions = {}): Promise<{ data: EventData[] }> => {
+      const params = new URLSearchParams();
+      for (const [k, v] of Object.entries(filters)) {
+        if (v !== undefined) params.append(k, Array.isArray(v) ? v.join(',') : String(v));
+      }
+      const qs = params.toString() ? `?${params.toString()}` : '';
+      return this.request<{ data: EventData[] }>(`public/${this.getOrgSlug()}/events${qs}`);
+    },
+
+    upcoming: async (tags?: string | string[], location?: string): Promise<{ data: EventData[] }> => {
+      const filters: EventsFilterOptions = { filter: 'upcoming' };
+      if (tags) filters.tags = tags;
+      if (location) filters.location = location;
+      return this.events.all(filters);
+    },
+
+    search: async (queryTerm: string): Promise<{ data: EventData[] }> => {
+      return this.request<{ data: EventData[] }>(`public/${this.getOrgSlug()}/events/search?q=${encodeURIComponent(queryTerm)}`);
+    },
+
+    find: async (eventIdOrSlug: number | string): Promise<{ data: EventData }> => {
+      return this.request<{ data: EventData }>(`public/${this.getOrgSlug()}/events/${eventIdOrSlug}`);
+    },
+
+    dates: async (eventIdOrSlug: number | string): Promise<{ data: EventDateData[] }> => {
+      return this.request<{ data: EventDateData[] }>(`public/${this.getOrgSlug()}/events/${eventIdOrSlug}/dates`);
+    },
+
+    date: async (eventDateId: number): Promise<{ data: EventDateData }> => {
+      return this.request<{ data: EventDateData }>(`public/${this.getOrgSlug()}/eventDates/${eventDateId}`);
+    },
+  };
+
+  // --- Locations ---
+
+  public readonly locations = {
+    all: async (filters: LocationsFilterOptions = {}): Promise<{ data: LocationData[] }> => {
+      const params = new URLSearchParams();
+      for (const [k, v] of Object.entries(filters)) {
+        if (v !== undefined) params.append(k, Array.isArray(v) ? v.join(',') : String(v));
+      }
+      const qs = params.toString() ? `?${params.toString()}` : '';
+      return this.request<{ data: LocationData[] }>(`public/${this.getOrgSlug()}/locations${qs}`);
+    },
+
+    find: async (locationIdOrStub: number | string): Promise<{ data: LocationData }> => {
+      return this.request<{ data: LocationData }>(`public/${this.getOrgSlug()}/locations/${locationIdOrStub}`);
+    },
+
+    mapData: async (): Promise<unknown> => {
+      return this.request(`public/${this.getOrgSlug()}/locations/map`);
+    },
+  };
+
+  // --- Forms ---
+
+  public readonly forms = {
+    all: async (): Promise<{ data: FormData[] }> => {
+      return this.request<{ data: FormData[] }>(`public/${this.getOrgSlug()}/forms`);
+    },
+
+    find: async (formIdOrSlug: number | string): Promise<{ data: FormData }> => {
+      return this.request<{ data: FormData }>(`public/${this.getOrgSlug()}/forms/${formIdOrSlug}`);
+    },
+
+    submit: async (formIdOrSlug: number | string, data: Record<string, unknown>): Promise<{ success: boolean; submission_id?: number }> => {
+      return this.request(`public/${this.getOrgSlug()}/forms/${formIdOrSlug}/submit`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ fields: data, data }),
+      });
+    },
+
+    signature: async (signingToken: string): Promise<{ data: FormSignatureData }> => {
+      return this.signatures.find(signingToken);
+    },
+
+    sign: async (signingToken: string, signatureData: string, name: string, email?: string): Promise<{ success: boolean }> => {
+      return this.signatures.signNative(signingToken, signatureData, name, email);
+    },
+  };
+
+  // --- Reviews ---
+
+  public readonly reviews = {
+    all: async (): Promise<{ data: ReviewData[] }> => {
+      return this.request<{ data: ReviewData[] }>('reviews');
+    },
+
+    create: async (data: Record<string, unknown>): Promise<{ data: ReviewData }> => {
+      return this.request<{ data: ReviewData }>('reviews', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(data),
+      });
+    },
+
+    updateStatus: async (reviewId: number, status: string): Promise<{ success: boolean }> => {
+      return this.request(`reviews/${reviewId}/status`, {
+        method: 'PATCH',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ status }),
+      });
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './client.js';
+export * from './webhooks.js';

package/src/types.ts

@@ -0,0 +1,218 @@
+export interface VenueFamilyConfig {
+  apiKey?: string;
+  organization?: string;
+  baseUrl?: string;
+  fetch?: typeof fetch;
+}
+
+export interface TagData {
+  id?: number;
+  name: string;
+  slug: string;
+}
+
+export interface LocationStub {
+  id: number;
+  name: string;
+  stub?: string;
+}
+
+export interface UserOrganizationData {
+  id: number;
+  name: string;
+  slug: string;
+}
+
+export interface UserData {
+  id: number;
+  name: string;
+  email: string;
+  first_name?: string;
+  last_name?: string;
+  chosen_name?: string;
+  artist_name?: string;
+  phone?: string;
+  bio?: string;
+  interests?: Array<{ id: number; name: string; description?: string; icon?: string }>;
+  organizations?: UserOrganizationData[];
+  is_staff?: boolean;
+  profile_photo_url?: string;
+  created_at?: string;
+}
+
+export interface RoleData {
+  id: number;
+  name: string;
+  slug: string;
+  scope: 'all' | 'own';
+  abilities?: string[];
+  status?: string;
+}
+
+export interface VolunteerRoleData {
+  id: number;
+  name: string;
+  description?: string;
+  date?: string;
+  start_time?: string;
+  end_time?: string;
+  spots_needed?: number;
+  spots_filled?: number;
+  status?: string;
+  organization_slug?: string;
+}
+
+export interface FormSignatureData {
+  id: number;
+  token: string;
+  status: 'pending' | 'signed' | 'countersigned' | 'cancelled' | 'expired';
+  mechanism: 'native' | 'certified';
+  name?: string;
+  email?: string;
+  signer_type?: string;
+  signed_at?: string;
+  signing_url?: string;
+}
+
+export interface EventDateData {
+  id: number;
+  date: string;
+  start_time: string;
+  end_time?: string;
+  door_time?: string;
+  status: string;
+  is_sold_out: boolean;
+  tickets_remaining?: number;
+  locations?: LocationStub[];
+}
+
+export interface EventData {
+  id: number;
+  title: string;
+  slug: string;
+  subtitle?: string;
+  summary?: string;
+  description?: string;
+  type?: string;
+  status?: string;
+  cover_image_url?: string;
+  ticket_price?: string;
+  tags?: TagData[];
+  locations?: LocationStub[];
+  upcoming_dates?: EventDateData[];
+}
+
+export interface SpaceData {
+  id: number;
+  name: string;
+  stub?: string;
+  capacity?: number;
+  price_per_hour?: string;
+}
+
+export interface LocationData {
+  id: number;
+  name: string;
+  stub?: string;
+  capacity?: number;
+  price_per_hour?: string;
+  address?: string;
+  city?: string;
+  state?: string;
+  zip?: string;
+  spaces?: SpaceData[];
+  features?: string[];
+}
+
+export interface FormFieldData {
+  id: string;
+  type: string;
+  label: string;
+  required?: boolean;
+  options?: string[];
+  placeholder?: string;
+}
+
+export interface FormData {
+  id: number;
+  title: string;
+  slug: string;
+  description?: string;
+  fields: FormFieldData[];
+}
+
+export interface ReviewData {
+  id: number;
+  rating?: number;
+  author_name?: string;
+  author_email?: string;
+  content?: string;
+  status?: string;
+  created_at?: string;
+}
+
+export interface EventsFilterOptions {
+  filter?: 'upcoming' | 'past' | 'recurring' | 'all';
+  start_date?: string;
+  end_date?: string;
+  location?: string;
+  type?: string;
+  tags?: string | string[];
+  search?: string;
+  q?: string;
+  limit?: number;
+  per_page?: number;
+  page?: number;
+}
+
+export interface LocationsFilterOptions {
+  city?: string;
+  state?: string;
+  capacity_min?: number;
+  capacity_max?: number;
+  price_min?: number;
+  price_max?: number;
+  features?: string | string[];
+  search?: string;
+  sort_by?: 'name' | 'capacity' | 'price_per_hour' | 'created_at';
+  sort_order?: 'asc' | 'desc';
+}
+
+// --- Embed postMessage Event Types ---
+
+export interface ResizeEmbedEvent {
+  type: 'resize';
+  height: number;
+}
+
+export interface ScrollIntoViewEmbedEvent {
+  type: 'scroll-into-view';
+  top: number;
+}
+
+export interface TicketPurchaseCompleteEmbedEvent {
+  type: 'ticket-purchase-complete';
+  orderNumber: string;
+  orderId: number;
+  status: string;
+  total: number; // in cents
+  quantity: number;
+  currency: string;
+  eventId: number;
+  eventName: string;
+}
+
+export interface FormSubmittedEmbedEvent {
+  type: 'form-submitted';
+  slug: string;
+  formId: number;
+  submissionId: number;
+}
+
+export type VenueFamilyEmbedEvent =
+  | ResizeEmbedEvent
+  | ScrollIntoViewEmbedEvent
+  | TicketPurchaseCompleteEmbedEvent
+  | FormSubmittedEmbedEvent
+  | { type: 'scroll-to-error' }
+  | { type: 'signin_success'; event?: unknown; organization?: unknown; eventDate?: unknown };