@queuezero/vue 0.1.3

package/README.md

@@ -0,0 +1,203 @@
+# @queuezero/vue
+
+Vue components and composables for QueueZero viral waitlists.
+
+## Installation
+
+```bash
+npm install @queuezero/vue
+```
+
+## Quick Start
+
+```vue
+<script setup>
+import { provideWaitlist, WaitlistForm, WaitlistStatus, ReferralShare } from '@queuezero/vue';
+
+// Get referral code from URL if present
+const referrerCode = new URLSearchParams(window.location.search).get('ref');
+
+// Provide waitlist to all child components
+provideWaitlist('my-campaign', { 
+  apiUrl: 'https://api.queuezero.io' 
+});
+</script>
+
+<template>
+  <WaitlistForm 
+    :referrer-code="referrerCode"
+    @success="(res) => console.log('Joined!', res)"
+  />
+  <WaitlistStatus />
+  <ReferralShare show-social-buttons />
+</template>
+```
+
+## Plugin Usage
+
+For app-wide integration:
+
+```ts
+import { createApp } from 'vue';
+import { createWaitlistPlugin } from '@queuezero/vue';
+
+const app = createApp(App);
+
+app.use(createWaitlistPlugin({
+  campaign: 'my-campaign',
+  config: { apiUrl: 'https://api.queuezero.io' }
+}));
+
+app.mount('#app');
+```
+
+## Components
+
+### WaitlistForm
+
+Ready-to-use signup form.
+
+```vue
+<template>
+  <!-- Basic -->
+  <WaitlistForm />
+
+  <!-- With options -->
+  <WaitlistForm
+    :referrer-code="referrerCode"
+    :metadata="{ role: 'Developer' }"
+    placeholder="Enter your work email"
+    button-text="Get Early Access"
+    @success="onSuccess"
+    @error="onError"
+  />
+
+  <!-- With scoped slot -->
+  <WaitlistForm v-slot="{ email, setEmail, submit, loading, error }">
+    <input :value="email" @input="setEmail($event.target.value)" />
+    <button @click="submit">{{ loading ? '...' : 'Join' }}</button>
+  </WaitlistForm>
+</template>
+```
+
+### WaitlistStatus
+
+Displays position, score, and referral count.
+
+```vue
+<template>
+  <!-- Basic -->
+  <WaitlistStatus />
+
+  <!-- With options -->
+  <WaitlistStatus
+    :show-score="true"
+    :show-referrals="true"
+    position-label="Your position:"
+  />
+
+  <!-- With scoped slot -->
+  <WaitlistStatus v-slot="status">
+    <h2>#{{ status.position }}</h2>
+    <p>{{ status.priority_score }} points</p>
+  </WaitlistStatus>
+</template>
+```
+
+### ReferralShare
+
+Share referral link with copy and social buttons.
+
+```vue
+<template>
+  <!-- Basic -->
+  <ReferralShare />
+
+  <!-- With social buttons -->
+  <ReferralShare 
+    show-social-buttons 
+    share-message="Join me on this awesome waitlist!" 
+  />
+
+  <!-- With scoped slot -->
+  <ReferralShare v-slot="{ link, code, copy, copied }">
+    <code>{{ code }}</code>
+    <button @click="copy">{{ copied ? 'Copied!' : 'Copy' }}</button>
+  </ReferralShare>
+</template>
+```
+
+## Composables
+
+### useWaitlist
+
+Standalone composable for full control.
+
+```vue
+<script setup>
+import { useWaitlist } from '@queuezero/vue';
+
+const { status, loading, join, getReferralLink } = useWaitlist('my-campaign', {
+  apiUrl: 'https://api.queuezero.io',
+});
+
+async function handleSubmit(email) {
+  await join(email, { role: 'Developer' });
+}
+</script>
+```
+
+### provideWaitlist / useWaitlistContext
+
+For component tree sharing.
+
+```vue
+<!-- Parent.vue -->
+<script setup>
+import { provideWaitlist } from '@queuezero/vue';
+
+provideWaitlist('my-campaign');
+</script>
+
+<!-- Child.vue -->
+<script setup>
+import { useWaitlistContext } from '@queuezero/vue';
+
+const { status, join } = useWaitlistContext();
+</script>
+```
+
+## Styling
+
+Components use `qz-*` class names:
+
+```css
+.qz-form { }
+.qz-form-row { display: flex; gap: 8px; }
+.qz-form-input { flex: 1; padding: 12px; }
+.qz-form-button { padding: 12px 24px; }
+.qz-form-error { color: red; }
+
+.qz-status { display: flex; gap: 16px; }
+.qz-status-label { font-size: 12px; }
+.qz-status-value { font-size: 24px; font-weight: bold; }
+
+.qz-share-input { flex: 1; }
+.qz-share-social { display: flex; gap: 8px; }
+```
+
+## TypeScript
+
+Full TypeScript support:
+
+```ts
+import type { 
+  UseWaitlistReturn,
+  WaitlistFormProps,
+  UserStatus 
+} from '@queuezero/vue';
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,374 @@
+import * as vue from 'vue';
+import { Ref, App, InjectionKey, PropType, VNode } from 'vue';
+import { UserStatus, PublicCampaignConfig, UserMetadata, SubmitResponse, QueueZeroConfig } from 'queuezero';
+export { InMemoryStorageAdapter, LeadStatus, LocalStorageAdapter, QueueZeroClient, QueueZeroConfig, SubmitResponse, UserMetadata, UserStatus } from 'queuezero';
+
+/**
+ * @queuezero/vue - Types
+ *
+ * TypeScript type definitions for Vue components and composables.
+ */
+
+/**
+ * Waitlist composable return value
+ */
+interface UseWaitlistReturn {
+    /** Current loading state */
+    loading: Ref<boolean>;
+    /** Current user status (if joined) */
+    status: Ref<UserStatus | null>;
+    /** Last error (if any) */
+    error: Ref<Error | null>;
+    /** Whether the user has joined */
+    isJoined: Ref<boolean>;
+    /** Public campaign configuration (branding, form fields, features) */
+    publicConfig: Ref<PublicCampaignConfig | null>;
+    /** Campaign slug */
+    campaign: string;
+    /** Join the waitlist */
+    join: (email: string, metadata?: UserMetadata, referrerCode?: string) => Promise<SubmitResponse | null>;
+    /** Refresh status */
+    refresh: () => Promise<UserStatus | null>;
+    /** Fetch public campaign configuration */
+    fetchPublicConfig: () => Promise<PublicCampaignConfig | null>;
+    /** Get referral link */
+    getReferralLink: () => string | null;
+    /** Get referral code */
+    getReferralCode: () => string | null;
+    /** Reset/logout */
+    reset: () => void;
+}
+/**
+ * Props for WaitlistForm component
+ */
+interface WaitlistFormProps {
+    /** Referral code (if from a referral link) */
+    referrerCode?: string;
+    /** Additional metadata to include */
+    metadata?: UserMetadata;
+    /** Custom placeholder text */
+    placeholder?: string;
+    /** Custom button text */
+    buttonText?: string;
+    /** Custom loading text */
+    loadingText?: string;
+    /** Show labels */
+    showLabel?: boolean;
+    /** Label text */
+    labelText?: string;
+}
+/**
+ * Props for WaitlistStatus component
+ */
+interface WaitlistStatusProps {
+    /** Show referral stats */
+    showReferrals?: boolean;
+    /** Show score */
+    showScore?: boolean;
+    /** Custom position label */
+    positionLabel?: string;
+    /** Custom score label */
+    scoreLabel?: string;
+    /** Custom referrals label */
+    referralsLabel?: string;
+}
+/**
+ * Props for ReferralShare component
+ */
+interface ReferralShareProps {
+    /** Text to display before the link */
+    label?: string;
+    /** Button text for copy action */
+    copyButtonText?: string;
+    /** Text shown after copying */
+    copiedText?: string;
+    /** Custom message for sharing */
+    shareMessage?: string;
+    /** Show social share buttons */
+    showSocialButtons?: boolean;
+}
+/**
+ * Plugin options for createWaitlist
+ */
+interface WaitlistPluginOptions {
+    /** Campaign slug/identifier */
+    campaign: string;
+    /** SDK configuration */
+    config?: QueueZeroConfig;
+}
+
+/**
+ * @queuezero/vue - Composables
+ *
+ * Vue composables for waitlist functionality.
+ */
+
+/**
+ * Injection key for waitlist context
+ */
+declare const WAITLIST_INJECTION_KEY: InjectionKey<UseWaitlistReturn>;
+/**
+ * useWaitlist - Composable for waitlist functionality
+ *
+ * Can be used standalone or with the plugin.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useWaitlist } from '@queuezero/vue';
+ *
+ * const { status, join, loading, getReferralLink, publicConfig } = useWaitlist('my-campaign');
+ *
+ * async function handleSubmit(email) {
+ *   await join(email, { role: 'Developer' });
+ * }
+ * </script>
+ * ```
+ */
+declare function useWaitlist(campaign?: string, config?: QueueZeroConfig): UseWaitlistReturn;
+/**
+ * provideWaitlist - Provide waitlist context to child components
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { provideWaitlist } from '@queuezero/vue';
+ *
+ * provideWaitlist('my-campaign', { apiUrl: 'https://api.example.com' });
+ * </script>
+ * ```
+ */
+declare function provideWaitlist(campaign: string, config?: QueueZeroConfig): UseWaitlistReturn;
+/**
+ * useWaitlistContext - Use provided waitlist context
+ *
+ * @throws Error if used outside of provider
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useWaitlistContext } from '@queuezero/vue';
+ *
+ * const { status, join } = useWaitlistContext();
+ * </script>
+ * ```
+ */
+declare function useWaitlistContext(): UseWaitlistReturn;
+/**
+ * createWaitlistPlugin - Create Vue plugin for app-wide waitlist
+ *
+ * @example
+ * ```ts
+ * import { createApp } from 'vue';
+ * import { createWaitlistPlugin } from '@queuezero/vue';
+ *
+ * const app = createApp(App);
+ * app.use(createWaitlistPlugin({ campaign: 'my-campaign' }));
+ * app.mount('#app');
+ * ```
+ */
+declare function createWaitlistPlugin(options: WaitlistPluginOptions): {
+    install(app: App): void;
+};
+
+declare const WaitlistForm: vue.DefineComponent<vue.ExtractPropTypes<{
+    referrerCode: {
+        type: PropType<string>;
+        default: undefined;
+    };
+    metadata: {
+        type: PropType<UserMetadata>;
+        default: () => {};
+    };
+    placeholder: {
+        type: StringConstructor;
+        default: string;
+    };
+    buttonText: {
+        type: StringConstructor;
+        default: string;
+    };
+    loadingText: {
+        type: StringConstructor;
+        default: string;
+    };
+    showLabel: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    labelText: {
+        type: StringConstructor;
+        default: string;
+    };
+}>, () => VNode<vue.RendererNode, vue.RendererElement, {
+    [key: string]: any;
+}> | VNode<vue.RendererNode, vue.RendererElement, {
+    [key: string]: any;
+}>[] | null, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {
+    success: (response: SubmitResponse) => true;
+    error: (error: Error) => true;
+}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
+    referrerCode: {
+        type: PropType<string>;
+        default: undefined;
+    };
+    metadata: {
+        type: PropType<UserMetadata>;
+        default: () => {};
+    };
+    placeholder: {
+        type: StringConstructor;
+        default: string;
+    };
+    buttonText: {
+        type: StringConstructor;
+        default: string;
+    };
+    loadingText: {
+        type: StringConstructor;
+        default: string;
+    };
+    showLabel: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    labelText: {
+        type: StringConstructor;
+        default: string;
+    };
+}>> & Readonly<{
+    onSuccess?: ((response: SubmitResponse) => any) | undefined;
+    onError?: ((error: Error) => any) | undefined;
+}>, {
+    placeholder: string;
+    referrerCode: string;
+    metadata: UserMetadata;
+    buttonText: string;
+    loadingText: string;
+    showLabel: boolean;
+    labelText: string;
+}, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
+
+/**
+ * @queuezero/vue - WaitlistStatus Component
+ *
+ * Displays the user's current waitlist position and stats.
+ */
+declare const WaitlistStatus: vue.DefineComponent<vue.ExtractPropTypes<{
+    showReferrals: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    showScore: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    positionLabel: {
+        type: StringConstructor;
+        default: string;
+    };
+    scoreLabel: {
+        type: StringConstructor;
+        default: string;
+    };
+    referralsLabel: {
+        type: StringConstructor;
+        default: string;
+    };
+}>, () => vue.VNode<vue.RendererNode, vue.RendererElement, {
+    [key: string]: any;
+}> | vue.VNode<vue.RendererNode, vue.RendererElement, {
+    [key: string]: any;
+}>[] | null, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
+    showReferrals: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    showScore: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    positionLabel: {
+        type: StringConstructor;
+        default: string;
+    };
+    scoreLabel: {
+        type: StringConstructor;
+        default: string;
+    };
+    referralsLabel: {
+        type: StringConstructor;
+        default: string;
+    };
+}>> & Readonly<{}>, {
+    showReferrals: boolean;
+    showScore: boolean;
+    positionLabel: string;
+    scoreLabel: string;
+    referralsLabel: string;
+}, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
+
+/**
+ * @queuezero/vue - ReferralShare Component
+ *
+ * Component for sharing referral links.
+ */
+declare const ReferralShare: vue.DefineComponent<vue.ExtractPropTypes<{
+    label: {
+        type: StringConstructor;
+        default: string;
+    };
+    copyButtonText: {
+        type: StringConstructor;
+        default: string;
+    };
+    copiedText: {
+        type: StringConstructor;
+        default: string;
+    };
+    shareMessage: {
+        type: StringConstructor;
+        default: string;
+    };
+    showSocialButtons: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+}>, () => vue.VNode<vue.RendererNode, vue.RendererElement, {
+    [key: string]: any;
+}> | vue.VNode<vue.RendererNode, vue.RendererElement, {
+    [key: string]: any;
+}>[] | null, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {
+    copy: (link: string) => true;
+}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
+    label: {
+        type: StringConstructor;
+        default: string;
+    };
+    copyButtonText: {
+        type: StringConstructor;
+        default: string;
+    };
+    copiedText: {
+        type: StringConstructor;
+        default: string;
+    };
+    shareMessage: {
+        type: StringConstructor;
+        default: string;
+    };
+    showSocialButtons: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+}>> & Readonly<{
+    onCopy?: ((link: string) => any) | undefined;
+}>, {
+    label: string;
+    copyButtonText: string;
+    copiedText: string;
+    shareMessage: string;
+    showSocialButtons: boolean;
+}, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
+
+export { ReferralShare, type ReferralShareProps, type UseWaitlistReturn, WAITLIST_INJECTION_KEY, WaitlistForm, type WaitlistFormProps, type WaitlistPluginOptions, WaitlistStatus, type WaitlistStatusProps, createWaitlistPlugin, provideWaitlist, useWaitlist, useWaitlistContext };