@venue-family/sdk 1.0.0

package/README.md

@@ -0,0 +1,123 @@
+# @venue-family/sdk
+
+Official TypeScript & JavaScript SDK for [Venue Family](https://venuefamily.com) — schedules, ticketing, dynamic forms, digital signatures, user authentication, and dynamic iframe embeds.
+
+---
+
+## Installation
+
+```bash
+npm install @venue-family/sdk
+# or
+pnpm add @venue-family/sdk
+# or
+yarn add @venue-family/sdk
+```
+
+---
+
+## Quick Start
+
+### 1. User Authentication & Profile
+
+```typescript
+import { VenueFamilyClient } from '@venue-family/sdk';
+
+const venue = new VenueFamilyClient({
+  organization: 'the-418-project',
+});
+
+// Login and obtain a session token
+const { token, user } = await venue.auth.login('artist@example.com', 'mypassword');
+
+// Initialize client with authenticated user token
+const authClient = new VenueFamilyClient({ apiKey: token });
+const me = await authClient.users.me();
+console.log(`Logged in as ${me.name} (Staff: ${me.is_staff})`);
+```
+
+### 2. Events & Locations
+
+```typescript
+// Fetch upcoming dance & workshop events
+const { data: events } = await venue.events.upcoming(['dance', 'workshop'], 'main-theater');
+
+events.forEach((event) => {
+  console.log(event.title, event.cover_image_url);
+  event.upcoming_dates?.forEach((date) => {
+    console.log(`- ${date.date} at ${date.start_time} (${date.tickets_remaining} tickets left)`);
+  });
+});
+```
+
+### 3. Form Submissions & Digital Signatures
+
+```typescript
+// Submit a dynamic intake waiver
+await venue.forms.submit('liability-waiver', {
+  full_name: 'Jane Doe',
+  emergency_phone: '831-555-0199',
+});
+
+// Check status of a signature request
+const { data: signature } = await venue.signatures.find('sig_token_xyz');
+console.log('Status:', signature.status); // 'pending', 'signed', 'countersigned'
+
+// Sign with native drawn/base64 signature
+if (signature.status === 'pending') {
+  await venue.signatures.signNative('sig_token_xyz', 'data:image/png;base64,...', 'Jane Doe');
+}
+```
+
+### 4. Auto-Resizing Dynamic Iframe Embeds & Conversion Tracking
+
+Venue Family embeds dynamically adapt their height via `postMessage`. Use the bundled helper in React, Vue, Svelte, or Vanilla JS:
+
+```typescript
+import { attachEmbedListener } from '@venue-family/sdk';
+
+const unsubscribe = attachEmbedListener('venue-family-embed', {
+  onResize: (height) => {
+    console.log('Embed height updated:', height);
+  },
+  onTicketPurchase: (order) => {
+    console.log('Ticket Purchased!', order.orderNumber, order.total, order.eventName);
+    
+    // Example: Trigger Google Ads or Meta Pixel conversion
+    if (typeof gtag === 'function') {
+      gtag('event', 'purchase', {
+        transaction_id: order.orderNumber,
+        value: order.total / 100,
+        currency: order.currency,
+      });
+    }
+  },
+});
+```
+
+### 5. Webhook Signature Verification (Node.js / Edge / Serverless)
+
+```typescript
+import { verifyWebhookSignature } from '@venue-family/sdk';
+
+export async function POST(request: Request) {
+  const payload = await request.text();
+  const signature = request.headers.get('x-vf-signature') || '';
+  const secret = process.env.VENUE_FAMILY_WEBHOOK_SECRET || '';
+
+  const isValid = await verifyWebhookSignature(payload, signature, secret);
+
+  if (!isValid) {
+    return new Response('Invalid signature', { status: 401 });
+  }
+
+  const event = JSON.parse(payload);
+  return Response.json({ received: true });
+}
+```
+
+---
+
+## License
+
+MIT License.

package/dist/client.d.ts

@@ -0,0 +1,117 @@
+import type { EventData, EventDateData, EventsFilterOptions, FormData, FormSignatureData, LocationData, LocationsFilterOptions, ReviewData, RoleData, UserData, VenueFamilyConfig, VolunteerRoleData } from './types.js';
+export declare class VenueFamilyClient {
+    private readonly baseUrl;
+    private readonly apiKey?;
+    private readonly organization?;
+    private readonly customFetch;
+    constructor(config?: VenueFamilyConfig);
+    forOrganization(organization: string): VenueFamilyClient;
+    private getOrgSlug;
+    private request;
+    readonly auth: {
+        login: (email: string, password: string, organizationSlug?: string, deviceName?: string) => Promise<{
+            token: string;
+            user: UserData;
+        }>;
+        register: (userData: Record<string, unknown>) => Promise<{
+            token: string;
+            user: UserData;
+        }>;
+        user: () => Promise<UserData>;
+        updateProfile: (attributes: Partial<UserData>) => Promise<UserData>;
+        updatePassword: (currentPassword: string, password: string, passwordConfirmation: string) => Promise<{
+            message: string;
+        }>;
+        logout: () => Promise<{
+            message: string;
+        }>;
+    };
+    readonly users: {
+        me: () => Promise<UserData>;
+        updateProfile: (attributes: Partial<UserData>) => Promise<UserData>;
+        myVolunteerRoles: () => Promise<{
+            data: VolunteerRoleData[];
+        }>;
+        volunteerOpportunities: () => Promise<{
+            data: VolunteerRoleData[];
+        }>;
+        signUpForVolunteerRole: (roleId: number) => Promise<{
+            success: boolean;
+        }>;
+    };
+    readonly roles: {
+        all: () => Promise<{
+            data: RoleData[];
+        }>;
+        find: (roleIdOrSlug: number | string) => Promise<{
+            data: RoleData;
+        }>;
+    };
+    readonly signatures: {
+        find: (signingToken: string) => Promise<{
+            data: FormSignatureData;
+        }>;
+        signNative: (signingToken: string, signatureData: string, name: string, email?: string) => Promise<{
+            success: boolean;
+        }>;
+        getSigningUrl: (signingToken: string) => string;
+    };
+    readonly events: {
+        all: (filters?: EventsFilterOptions) => Promise<{
+            data: EventData[];
+        }>;
+        upcoming: (tags?: string | string[], location?: string) => Promise<{
+            data: EventData[];
+        }>;
+        search: (queryTerm: string) => Promise<{
+            data: EventData[];
+        }>;
+        find: (eventIdOrSlug: number | string) => Promise<{
+            data: EventData;
+        }>;
+        dates: (eventIdOrSlug: number | string) => Promise<{
+            data: EventDateData[];
+        }>;
+        date: (eventDateId: number) => Promise<{
+            data: EventDateData;
+        }>;
+    };
+    readonly locations: {
+        all: (filters?: LocationsFilterOptions) => Promise<{
+            data: LocationData[];
+        }>;
+        find: (locationIdOrStub: number | string) => Promise<{
+            data: LocationData;
+        }>;
+        mapData: () => Promise<unknown>;
+    };
+    readonly forms: {
+        all: () => Promise<{
+            data: FormData[];
+        }>;
+        find: (formIdOrSlug: number | string) => Promise<{
+            data: FormData;
+        }>;
+        submit: (formIdOrSlug: number | string, data: Record<string, unknown>) => Promise<{
+            success: boolean;
+            submission_id?: number;
+        }>;
+        signature: (signingToken: string) => Promise<{
+            data: FormSignatureData;
+        }>;
+        sign: (signingToken: string, signatureData: string, name: string, email?: string) => Promise<{
+            success: boolean;
+        }>;
+    };
+    readonly reviews: {
+        all: () => Promise<{
+            data: ReviewData[];
+        }>;
+        create: (data: Record<string, unknown>) => Promise<{
+            data: ReviewData;
+        }>;
+        updateStatus: (reviewId: number, status: string) => Promise<{
+            success: boolean;
+        }>;
+    };
+}

package/dist/client.js

@@ -0,0 +1,231 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VenueFamilyClient = void 0;
+class VenueFamilyClient {
+    baseUrl;
+    apiKey;
+    organization;
+    customFetch;
+    constructor(config = {}) {
+        this.baseUrl = (config.baseUrl ?? 'https://venuefamily.com/api').replace(/\/+$/, '');
+        this.apiKey = config.apiKey;
+        this.organization = config.organization;
+        this.customFetch = config.fetch ?? fetch.bind(globalThis);
+    }
+    forOrganization(organization) {
+        return new VenueFamilyClient({
+            baseUrl: this.baseUrl,
+            apiKey: this.apiKey,
+            organization,
+            fetch: this.customFetch,
+        });
+    }
+    getOrgSlug() {
+        if (!this.organization) {
+            throw new Error('Organization slug is required. Pass organization in config or use client.forOrganization("slug").');
+        }
+        return this.organization;
+    }
+    async request(path, options = {}) {
+        const url = `${this.baseUrl}/${path.replace(/^\/+/, '')}`;
+        const headers = {
+            Accept: 'application/json',
+            ...(options.headers || {}),
+        };
+        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();
+    }
+    // --- Auth & User Management ---
+    auth = {
+        login: async (email, password, organizationSlug, deviceName = 'TS SDK') => {
+            const body = { 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) => {
+            return this.request('auth/register', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(userData),
+            });
+        },
+        user: async () => {
+            const res = await this.request('auth/user');
+            return res.user;
+        },
+        updateProfile: async (attributes) => {
+            const res = await this.request('auth/profile', {
+                method: 'PUT',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(attributes),
+            });
+            return res.user;
+        },
+        updatePassword: async (currentPassword, password, passwordConfirmation) => {
+            return this.request('auth/password', {
+                method: 'PUT',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    current_password: currentPassword,
+                    password,
+                    password_confirmation: passwordConfirmation,
+                }),
+            });
+        },
+        logout: async () => {
+            return this.request('auth/logout', { method: 'POST' });
+        },
+    };
+    users = {
+        me: async () => this.auth.user(),
+        updateProfile: async (attributes) => this.auth.updateProfile(attributes),
+        myVolunteerRoles: async () => this.request('volunteer-roles/my-roles'),
+        volunteerOpportunities: async () => this.request('volunteer-opportunities'),
+        signUpForVolunteerRole: async (roleId) => {
+            return this.request('volunteer-roles/sign-up', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ role_id: roleId }),
+            });
+        },
+    };
+    roles = {
+        all: async () => this.request('roles'),
+        find: async (roleIdOrSlug) => this.request(`roles/${roleIdOrSlug}`),
+    };
+    signatures = {
+        find: async (signingToken) => this.request(`signatures/${signingToken}`),
+        signNative: async (signingToken, signatureData, name, email) => {
+            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) => {
+            const rootUrl = this.baseUrl.replace(/\/api\/?$/, '');
+            return `${rootUrl}/forms/countersign/${signingToken}`;
+        },
+    };
+    // --- Events ---
+    events = {
+        all: async (filters = {}) => {
+            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(`public/${this.getOrgSlug()}/events${qs}`);
+        },
+        upcoming: async (tags, location) => {
+            const filters = { filter: 'upcoming' };
+            if (tags)
+                filters.tags = tags;
+            if (location)
+                filters.location = location;
+            return this.events.all(filters);
+        },
+        search: async (queryTerm) => {
+            return this.request(`public/${this.getOrgSlug()}/events/search?q=${encodeURIComponent(queryTerm)}`);
+        },
+        find: async (eventIdOrSlug) => {
+            return this.request(`public/${this.getOrgSlug()}/events/${eventIdOrSlug}`);
+        },
+        dates: async (eventIdOrSlug) => {
+            return this.request(`public/${this.getOrgSlug()}/events/${eventIdOrSlug}/dates`);
+        },
+        date: async (eventDateId) => {
+            return this.request(`public/${this.getOrgSlug()}/eventDates/${eventDateId}`);
+        },
+    };
+    // --- Locations ---
+    locations = {
+        all: async (filters = {}) => {
+            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(`public/${this.getOrgSlug()}/locations${qs}`);
+        },
+        find: async (locationIdOrStub) => {
+            return this.request(`public/${this.getOrgSlug()}/locations/${locationIdOrStub}`);
+        },
+        mapData: async () => {
+            return this.request(`public/${this.getOrgSlug()}/locations/map`);
+        },
+    };
+    // --- Forms ---
+    forms = {
+        all: async () => {
+            return this.request(`public/${this.getOrgSlug()}/forms`);
+        },
+        find: async (formIdOrSlug) => {
+            return this.request(`public/${this.getOrgSlug()}/forms/${formIdOrSlug}`);
+        },
+        submit: async (formIdOrSlug, data) => {
+            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) => {
+            return this.signatures.find(signingToken);
+        },
+        sign: async (signingToken, signatureData, name, email) => {
+            return this.signatures.signNative(signingToken, signatureData, name, email);
+        },
+    };
+    // --- Reviews ---
+    reviews = {
+        all: async () => {
+            return this.request('reviews');
+        },
+        create: async (data) => {
+            return this.request('reviews', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(data),
+            });
+        },
+        updateStatus: async (reviewId, status) => {
+            return this.request(`reviews/${reviewId}/status`, {
+                method: 'PATCH',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ status }),
+            });
+        },
+    };
+}
+exports.VenueFamilyClient = VenueFamilyClient;

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types.js"), exports);
+__exportStar(require("./client.js"), exports);
+__exportStar(require("./webhooks.js"), exports);

package/dist/types.d.ts

@@ -0,0 +1,201 @@
+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';
+}
+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;
+    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;
+};

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });