@timeback/sdk 0.1.6 → 0.1.8

package/dist/client/adapters/svelte/stores/profile.ts

@@ -0,0 +1,168 @@
+/**
+ * Timeback Profile Store
+ *
+ * Svelte store for user profile state.
+ */
+
+import { fetchProfileOnce, getProfileCache } from '../../../lib/user-cache'
+import { getClientInstance } from './client'
+import { writable } from 'svelte/store'
+import { verificationStore } from './verification'
+
+import type { TimebackProfileState, TimebackVerificationState } from '../types'
+import type { Readable } from 'svelte/store'
+
+const profileStore = writable<TimebackProfileState>({ status: 'idle' })
+const canFetchStore = writable<boolean>(false)
+let profileInitialized = false
+
+/**
+ * Check if we're running in the browser.
+ *
+ * @returns True if in browser
+ */
+function isBrowser(): boolean {
+	return typeof window !== 'undefined'
+}
+
+/**
+ * Run the profile fetch.
+ *
+ * @param force - If true, bypass cache and force a fresh fetch
+ */
+async function runProfileFetch(force: boolean): Promise<void> {
+	const client = getClientInstance()
+	if (!client) return
+
+	if (!force) {
+		const cached = getProfileCache(client)
+		if (cached) {
+			profileStore.set({ status: 'loaded', profile: cached })
+			return
+		}
+	}
+
+	profileStore.set({ status: 'loading' })
+
+	try {
+		const profile = await fetchProfileOnce(client, force)
+		profileStore.set({ status: 'loaded', profile })
+	} catch (err) {
+		profileStore.set({
+			status: 'error',
+			message: err instanceof Error ? err.message : 'Failed to fetch profile',
+		})
+	}
+}
+
+/**
+ * Update canFetch based on verification state.
+ *
+ * @param verification - Current verification state
+ */
+function updateCanFetch(verification: TimebackVerificationState): void {
+	const can = verification.status === 'verified' && !!getClientInstance()
+	canFetchStore.set(can)
+}
+
+/**
+ * Initialize profile store subscriptions.
+ */
+function initProfile(): void {
+	if (profileInitialized) return
+	profileInitialized = true
+
+	verificationStore.subscribe(verification => {
+		updateCanFetch(verification)
+
+		// Reset to idle if not verified
+		if (verification.status !== 'verified') {
+			profileStore.set({ status: 'idle' })
+		}
+	})
+}
+
+// Auto-init in browser
+if (isBrowser()) {
+	initProfile()
+}
+
+/**
+ * Store containing the Timeback profile state.
+ *
+ * Use this to access the current user's Timeback profile.
+ * Call `fetchTimebackProfile()` to manually fetch, or `refreshTimebackProfile()` to force re-fetch.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { timebackProfile, timebackProfileCanFetch, fetchTimebackProfile } from '@timeback/sdk/svelte'
+ * </script>
+ *
+ * <button on:click={fetchTimebackProfile} disabled={!$timebackProfileCanFetch}>
+ *   {$timebackProfile.status === 'loading' ? 'Loading...' : 'Fetch Profile'}
+ * </button>
+ *
+ * {#if $timebackProfile.status === 'loaded'}
+ *   <pre>{JSON.stringify($timebackProfile.profile, null, 2)}</pre>
+ * {/if}
+ * ```
+ */
+export const timebackProfile: Readable<TimebackProfileState> = profileStore
+
+/**
+ * Store indicating whether the profile can be fetched.
+ *
+ * True when the user is verified and the client is ready.
+ */
+export const timebackProfileCanFetch: Readable<boolean> = canFetchStore
+
+/**
+ * Manually fetch the Timeback profile.
+ *
+ * No-op if the user is not verified or client is not ready.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { fetchTimebackProfile } from '@timeback/sdk/svelte'
+ * </script>
+ *
+ * <button on:click={fetchTimebackProfile}>Fetch Profile</button>
+ * ```
+ */
+export function fetchTimebackProfile(): void {
+	if (!isBrowser()) return
+
+	let canFetch = false
+	canFetchStore.subscribe(v => (canFetch = v))()
+
+	if (!canFetch) return
+
+	void runProfileFetch(false)
+}
+
+/**
+ * Force a re-fetch of the Timeback profile.
+ *
+ * No-op if the user is not verified or client is not ready.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { refreshTimebackProfile } from '@timeback/sdk/svelte'
+ * </script>
+ *
+ * <button on:click={refreshTimebackProfile}>Refresh Profile</button>
+ * ```
+ */
+export function refreshTimebackProfile(): void {
+	if (!isBrowser()) return
+
+	let canFetch = false
+	canFetchStore.subscribe(v => (canFetch = v))()
+
+	if (!canFetch) return
+
+	void runProfileFetch(true)
+}

package/dist/client/adapters/svelte/stores/verification.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Timeback Verification Store
+ *
+ * Svelte store for user verification state.
+ */
+import type { TimebackVerificationState } from '../types';
+import type { Readable } from 'svelte/store';
+export declare const verificationStore: import("svelte/store").Writable<TimebackVerificationState>;
+/**
+ * Store containing the Timeback verification state.
+ *
+ * Use this to check if the current user is verified in Timeback.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { timebackVerification, refreshTimebackVerification } from '@timeback/sdk/svelte'
+ * </script>
+ *
+ * {#if $timebackVerification.status === 'verified'}
+ *   <p>Verified! Timeback ID: {$timebackVerification.timebackId}</p>
+ * {:else if $timebackVerification.status === 'loading'}
+ *   <p>Verifying...</p>
+ * {:else}
+ *   <p>Not verified</p>
+ * {/if}
+ * ```
+ */
+export declare const timebackVerification: Readable<TimebackVerificationState>;
+/**
+ * Force a re-verification of the current user.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { refreshTimebackVerification } from '@timeback/sdk/svelte'
+ * </script>
+ *
+ * <button on:click={refreshTimebackVerification}>Refresh Verification</button>
+ * ```
+ */
+export declare function refreshTimebackVerification(): void;
+//# sourceMappingURL=verification.d.ts.map

package/dist/client/adapters/svelte/stores/verification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verification.d.ts","sourceRoot":"","sources":["../../../../../src/client/adapters/svelte/stores/verification.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,UAAU,CAAA;AACzD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AAc5C,eAAO,MAAM,iBAAiB,4DAA6D,CAAA;AA8D3F;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,yBAAyB,CAAqB,CAAA;AAE1F;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,IAAI,IAAI,CAGlD"}

package/dist/client/adapters/svelte/stores/verification.ts

@@ -0,0 +1,126 @@
+/**
+ * Timeback Verification Store
+ *
+ * Svelte store for user verification state.
+ */
+
+import { getVerifyCache, verifyOnce } from '../../../lib/user-cache'
+import { clientStore, getClientInstance } from './client'
+import { writable } from 'svelte/store'
+
+import type { TimebackVerifyResult } from '../../../../shared/types'
+import type { TimebackVerificationState } from '../types'
+import type { Readable } from 'svelte/store'
+
+/**
+ * Convert a verify result into a store-friendly state machine.
+ *
+ * @param result - Raw verify result from the SDK client
+ * @returns Mapped verification state
+ */
+function toVerificationState(result: TimebackVerifyResult): TimebackVerificationState {
+	return result.verified
+		? { status: 'verified', timebackId: result.timebackId }
+		: { status: 'unverified' }
+}
+
+export const verificationStore = writable<TimebackVerificationState>({ status: 'loading' })
+let verificationInitialized = false
+
+/**
+ * Check if we're running in the browser.
+ *
+ * @returns True if in browser
+ */
+function isBrowser(): boolean {
+	return typeof window !== 'undefined'
+}
+
+/**
+ * Run the verification check.
+ *
+ * @param force - If true, bypass cache and force a fresh verification
+ */
+async function runVerification(force: boolean): Promise<void> {
+	const client = getClientInstance()
+	if (!client) return
+
+	if (!force) {
+		const cached = getVerifyCache(client)
+		if (cached) {
+			verificationStore.set(toVerificationState(cached))
+			return
+		}
+	}
+
+	verificationStore.set({ status: 'loading' })
+
+	try {
+		const result = await verifyOnce(client, force)
+		verificationStore.set(toVerificationState(result))
+	} catch (err) {
+		verificationStore.set({
+			status: 'error',
+			message: err instanceof Error ? err.message : 'Failed to verify Timeback user',
+		})
+	}
+}
+
+/**
+ * Initialize verification when client becomes available.
+ */
+function initVerification(): void {
+	if (verificationInitialized) return
+	verificationInitialized = true
+
+	// Subscribe to client changes to auto-verify
+	clientStore.subscribe(client => {
+		if (client && isBrowser()) {
+			void runVerification(false)
+		}
+	})
+}
+
+// Auto-init in browser
+if (isBrowser()) {
+	initVerification()
+}
+
+/**
+ * Store containing the Timeback verification state.
+ *
+ * Use this to check if the current user is verified in Timeback.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { timebackVerification, refreshTimebackVerification } from '@timeback/sdk/svelte'
+ * </script>
+ *
+ * {#if $timebackVerification.status === 'verified'}
+ *   <p>Verified! Timeback ID: {$timebackVerification.timebackId}</p>
+ * {:else if $timebackVerification.status === 'loading'}
+ *   <p>Verifying...</p>
+ * {:else}
+ *   <p>Not verified</p>
+ * {/if}
+ * ```
+ */
+export const timebackVerification: Readable<TimebackVerificationState> = verificationStore
+
+/**
+ * Force a re-verification of the current user.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { refreshTimebackVerification } from '@timeback/sdk/svelte'
+ * </script>
+ *
+ * <button on:click={refreshTimebackVerification}>Refresh Verification</button>
+ * ```
+ */
+export function refreshTimebackVerification(): void {
+	if (!isBrowser()) return
+	void runVerification(true)
+}

package/dist/client/adapters/svelte/types.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Svelte Types
+ *
+ * Types for Svelte-specific stores.
+ */
+import type { TimebackProfile } from '../../../shared/types';
+/**
+ * Verification state for the current user.
+ */
+export type TimebackVerificationState = {
+    status: 'loading';
+} | {
+    status: 'verified';
+    timebackId: string;
+} | {
+    status: 'unverified';
+} | {
+    status: 'error';
+    message: string;
+};
+/**
+ * Profile state for the current user.
+ */
+export type TimebackProfileState = {
+    status: 'idle';
+} | {
+    status: 'loading';
+} | {
+    status: 'loaded';
+    profile: TimebackProfile;
+} | {
+    status: 'error';
+    message: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/client/adapters/svelte/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/client/adapters/svelte/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAE5D;;GAEG;AACH,MAAM,MAAM,yBAAyB,GAClC;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,GACrB;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,MAAM,EAAE,YAAY,CAAA;CAAE,GACxB;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAA;AAEvC;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAC7B;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAClB;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,GACrB;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,eAAe,CAAA;CAAE,GAC9C;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAA"}

package/dist/client/adapters/vue/composables/useTimebackProfile.d.ts

@@ -0,0 +1,51 @@
+/**
+ * useTimebackProfile
+ *
+ * Vue composable for fetching the current user's Timeback profile.
+ *
+ * This composable uses `useTimebackVerification` internally and only fetches
+ * the profile when the user is verified (i.e., exists in Timeback).
+ */
+import type { ComputedRef, Ref } from 'vue';
+import type { TimebackProfileState, UseTimebackProfileOptions } from '../types';
+/**
+ * Fetch the current user's Timeback profile.
+ *
+ * This composable internally uses `useTimebackVerification` to ensure the user
+ * is verified before fetching. When `auto: true`, it automatically fetches
+ * the profile once verified. Otherwise, call `fetchProfile()` manually.
+ *
+ * @param options - Composable options
+ * @param options.enabled - If false, the composable does nothing and stays in idle state. Defaults to true.
+ * @param options.auto - If true, automatically fetch once verified. Defaults to false.
+ * @returns Profile state and fetch methods
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useTimebackProfile } from '@timeback/sdk/vue'
+ *
+ * // Manual fetch
+ * const { state, canFetch, fetchProfile } = useTimebackProfile()
+ *
+ * // Or auto-fetch
+ * // const { state } = useTimebackProfile({ auto: true })
+ * </script>
+ *
+ * <template>
+ *   <div v-if="state.status === 'loaded'">
+ *     XP: {{ state.profile.xp }}
+ *   </div>
+ *   <button v-else @click="fetchProfile" :disabled="!canFetch">
+ *     {{ state.status === 'loading' ? 'Loading...' : 'Load Profile' }}
+ *   </button>
+ * </template>
+ * ```
+ */
+export declare function useTimebackProfile(options?: UseTimebackProfileOptions): {
+    state: Ref<TimebackProfileState>;
+    canFetch: ComputedRef<boolean>;
+    fetchProfile: () => void;
+    refresh: () => void;
+};
+//# sourceMappingURL=useTimebackProfile.d.ts.map

package/dist/client/adapters/vue/composables/useTimebackProfile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTimebackProfile.d.ts","sourceRoot":"","sources":["../../../../../src/client/adapters/vue/composables/useTimebackProfile.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,OAAO,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,KAAK,CAAA;AAC3C,OAAO,KAAK,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,UAAU,CAAA;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,yBAA8B,GAAG;IAC5E,KAAK,EAAE,GAAG,CAAC,oBAAoB,CAAC,CAAA;IAChC,QAAQ,EAAE,WAAW,CAAC,OAAO,CAAC,CAAA;IAC9B,YAAY,EAAE,MAAM,IAAI,CAAA;IACxB,OAAO,EAAE,MAAM,IAAI,CAAA;CACnB,CAgIA"}

package/dist/client/adapters/vue/composables/useTimebackProfile.ts

@@ -0,0 +1,186 @@
+/**
+ * useTimebackProfile
+ *
+ * Vue composable for fetching the current user's Timeback profile.
+ *
+ * This composable uses `useTimebackVerification` internally and only fetches
+ * the profile when the user is verified (i.e., exists in Timeback).
+ */
+
+import { computed, ref, watch } from 'vue'
+
+import { fetchProfileOnce, getProfileCache } from '../../../lib/user-cache'
+import { useTimeback } from '../provider'
+import { useTimebackVerification } from './useTimebackVerification'
+
+import type { ComputedRef, Ref } from 'vue'
+import type { TimebackProfileState, UseTimebackProfileOptions } from '../types'
+
+/**
+ * Fetch the current user's Timeback profile.
+ *
+ * This composable internally uses `useTimebackVerification` to ensure the user
+ * is verified before fetching. When `auto: true`, it automatically fetches
+ * the profile once verified. Otherwise, call `fetchProfile()` manually.
+ *
+ * @param options - Composable options
+ * @param options.enabled - If false, the composable does nothing and stays in idle state. Defaults to true.
+ * @param options.auto - If true, automatically fetch once verified. Defaults to false.
+ * @returns Profile state and fetch methods
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useTimebackProfile } from '@timeback/sdk/vue'
+ *
+ * // Manual fetch
+ * const { state, canFetch, fetchProfile } = useTimebackProfile()
+ *
+ * // Or auto-fetch
+ * // const { state } = useTimebackProfile({ auto: true })
+ * </script>
+ *
+ * <template>
+ *   <div v-if="state.status === 'loaded'">
+ *     XP: {{ state.profile.xp }}
+ *   </div>
+ *   <button v-else @click="fetchProfile" :disabled="!canFetch">
+ *     {{ state.status === 'loading' ? 'Loading...' : 'Load Profile' }}
+ *   </button>
+ * </template>
+ * ```
+ */
+export function useTimebackProfile(options: UseTimebackProfileOptions = {}): {
+	state: Ref<TimebackProfileState>
+	canFetch: ComputedRef<boolean>
+	fetchProfile: () => void
+	refresh: () => void
+} {
+	const { enabled = true, auto = false } = options
+
+	const timebackRef = useTimeback()
+	const { state: verificationState } = useTimebackVerification({ enabled })
+
+	const state = ref<TimebackProfileState>({ status: 'idle' }) as Ref<TimebackProfileState>
+	const fetchNonce = ref(0)
+	const refreshNonce = ref(0)
+
+	let lastHandledFetchNonce = 0
+	let lastHandledRefreshNonce = 0
+	let autoTriggered = false
+
+	const canFetch = computed(
+		() => enabled && verificationState.value.status === 'verified' && !!timebackRef.value,
+	)
+
+	const fetchProfile = () => {
+		if (!canFetch.value) {
+			return
+		}
+
+		fetchNonce.value++
+	}
+
+	const refresh = () => {
+		if (!canFetch.value) {
+			return
+		}
+
+		refreshNonce.value++
+	}
+
+	watch(
+		[verificationState, fetchNonce, refreshNonce, () => timebackRef.value],
+		async ([verification, fetchN, refreshN, timeback], _prev, onCleanup) => {
+			if (!enabled) {
+				state.value = { status: 'idle' }
+
+				return
+			}
+
+			let cancelled = false
+
+			onCleanup(() => {
+				cancelled = true
+			})
+
+			if (verification.status !== 'verified') {
+				if (state.value.status !== 'idle') {
+					state.value = { status: 'idle' }
+				}
+
+				autoTriggered = false
+
+				return
+			}
+
+			if (auto && !autoTriggered && fetchN === 0 && refreshN === 0) {
+				autoTriggered = true
+				fetchNonce.value = 1
+				return
+			}
+
+			if (fetchN === 0 && refreshN === 0) {
+				return
+			}
+
+			const isNewFetch = fetchN > lastHandledFetchNonce
+			const isNewRefresh = refreshN > lastHandledRefreshNonce
+			const force = isNewRefresh
+
+			if (!isNewFetch && !isNewRefresh) {
+				if (timeback) {
+					const cached = getProfileCache(timeback)
+
+					if (cached) {
+						state.value = { status: 'loaded', profile: cached }
+
+						return
+					}
+				}
+
+				return
+			}
+
+			if (timeback && !force) {
+				const cached = getProfileCache(timeback)
+
+				if (cached) {
+					state.value = { status: 'loaded', profile: cached }
+					lastHandledFetchNonce = fetchN
+
+					return
+				}
+			}
+
+			state.value = { status: 'loading' }
+
+			try {
+				if (!timeback) {
+					return
+				}
+
+				lastHandledFetchNonce = fetchN
+				lastHandledRefreshNonce = refreshN
+
+				const profile = await fetchProfileOnce(timeback, force)
+
+				if (cancelled) {
+					return
+				}
+
+				state.value = { status: 'loaded', profile }
+			} catch (err) {
+				if (!cancelled) {
+					state.value = {
+						status: 'error',
+						message: err instanceof Error ? err.message : 'Failed to fetch profile',
+					}
+				}
+			}
+		},
+		{ immediate: true },
+	)
+
+	return { state, canFetch, fetchProfile, refresh }
+}

package/dist/client/adapters/vue/composables/useTimebackVerification.d.ts

@@ -0,0 +1,44 @@
+/**
+ * useTimebackVerification
+ *
+ * Vue composable for checking whether the current user can be verified in Timeback.
+ *
+ * This is a lightweight check (backed by `/api/timeback/user/verify`) and is
+ * intended for partner gating flows (e.g., "free for Timeback users").
+ */
+import type { Ref } from 'vue';
+import type { TimebackVerificationState, UseTimebackVerificationOptions } from '../types';
+/**
+ * Verify the current user against Timeback.
+ *
+ * The composable runs automatically once the Timeback client is available, and
+ * provides a `refresh()` method to retry.
+ *
+ * @param options - Composable options
+ * @param options.enabled - If false, the composable does nothing and stays in loading state.
+ * @returns Verification state and a refresh method
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useTimebackVerification } from '@timeback/sdk/vue'
+ *
+ * const { state, refresh } = useTimebackVerification()
+ * </script>
+ *
+ * <template>
+ *   <div v-if="state.status === 'verified'">
+ *     Verified as {{ state.timebackId }}
+ *   </div>
+ *   <div v-else-if="state.status === 'loading'">
+ *     Verifying...
+ *   </div>
+ *   <button @click="refresh">Refresh</button>
+ * </template>
+ * ```
+ */
+export declare function useTimebackVerification(options?: UseTimebackVerificationOptions): {
+    state: Ref<TimebackVerificationState>;
+    refresh: () => void;
+};
+//# sourceMappingURL=useTimebackVerification.d.ts.map

package/dist/client/adapters/vue/composables/useTimebackVerification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTimebackVerification.d.ts","sourceRoot":"","sources":["../../../../../src/client/adapters/vue/composables/useTimebackVerification.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,KAAK,CAAA;AAE9B,OAAO,KAAK,EAAE,yBAAyB,EAAE,8BAA8B,EAAE,MAAM,UAAU,CAAA;AAczF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,uBAAuB,CACtC,OAAO,GAAE,8BAAmC,GAC1C;IACF,KAAK,EAAE,GAAG,CAAC,yBAAyB,CAAC,CAAA;IACrC,OAAO,EAAE,MAAM,IAAI,CAAA;CACnB,CA+DA"}