@timeback/sdk 0.1.7 → 0.1.8

package/dist/client/adapters/solid/primitives/createTimebackProfile.ts

@@ -0,0 +1,209 @@
+/**
+ * createTimebackProfile
+ *
+ * Solid primitive for fetching the current user's Timeback profile.
+ *
+ * Composes `createTimebackVerification` internally and only fetches
+ * the profile when the user is verified (i.e., exists in Timeback).
+ */
+
+import { createEffect, createMemo, createSignal, onCleanup } from 'solid-js'
+
+import { fetchProfileOnce, getProfileCache } from '../../../lib/user-cache'
+import { useTimeback } from '../context'
+import { createTimebackVerification } from './createTimebackVerification'
+
+import type {
+	CreateTimebackProfileOptions,
+	CreateTimebackProfileResult,
+	TimebackProfileState,
+} from '../types'
+
+/**
+ * Fetch the current user's Timeback profile.
+ *
+ * Internally uses `createTimebackVerification` to ensure the user
+ * is verified before fetching. When `auto: true`, it automatically fetches
+ * the profile once verified. Otherwise, call `fetchProfile()` manually.
+ *
+ * @param options - Options
+ * @param options.enabled - If false, 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
+ * ```tsx
+ * // Manual fetch
+ * import { createTimebackProfile } from '@timeback/sdk/solid'
+ * import { Show } from 'solid-js'
+ *
+ * function ProfileButton() {
+ *   const { state, canFetch, fetchProfile } = createTimebackProfile()
+ *
+ *   return (
+ *     <Show
+ *       when={state.status === 'loaded'}
+ *       fallback={
+ *         <button onClick={fetchProfile} disabled={!canFetch}>
+ *           {state.status === 'loading' ? 'Loading...' : 'Load Profile'}
+ *         </button>
+ *       }
+ *     >
+ *       <div>XP: {state.profile.xp}</div>
+ *     </Show>
+ *   )
+ * }
+ *
+ * // Auto-fetch
+ * function AutoProfile() {
+ *   const { state } = createTimebackProfile({ auto: true })
+ *
+ *   return (
+ *     <Show when={state.status === 'loading'}>
+ *       <div>Loading...</div>
+ *     </Show>
+ *   )
+ * }
+ * ```
+ */
+export function createTimebackProfile(
+	options: CreateTimebackProfileOptions = {},
+): CreateTimebackProfileResult {
+	const { enabled = true, auto = false } = options
+
+	const timeback = useTimeback()
+	const verification = createTimebackVerification({ enabled })
+
+	const [state, setState] = createSignal<TimebackProfileState>({ status: 'idle' })
+	const [fetchNonce, setFetchNonce] = createSignal(0)
+	const [refreshNonce, setRefreshNonce] = createSignal(0)
+
+	let lastHandledFetchNonce = 0
+	let lastHandledRefreshNonce = 0
+	let autoTriggered = false
+
+	const canFetch = createMemo(
+		() => enabled && verification.state.status === 'verified' && !!timeback,
+	)
+
+	const fetchProfile = () => {
+		if (!canFetch()) {
+			return
+		}
+
+		setFetchNonce(n => n + 1)
+	}
+
+	const refresh = () => {
+		if (!canFetch()) {
+			return
+		}
+
+		setRefreshNonce(n => n + 1)
+	}
+
+	createEffect(() => {
+		const verificationState = verification.state
+		const fetchN = fetchNonce()
+		const refreshN = refreshNonce()
+
+		if (!enabled) {
+			setState({ status: 'idle' })
+			return
+		}
+
+		if (verificationState.status !== 'verified') {
+			setState(current => (current.status === 'idle' ? current : { status: 'idle' }))
+			autoTriggered = false
+			return
+		}
+
+		if (auto && !autoTriggered && fetchN === 0 && refreshN === 0) {
+			autoTriggered = true
+			setFetchNonce(1)
+			return
+		}
+
+		if (fetchN === 0 && refreshN === 0) {
+			return
+		}
+
+		let cancelled = false
+		const isNewFetch = fetchN > lastHandledFetchNonce
+		const isNewRefresh = refreshN > lastHandledRefreshNonce
+		const force = isNewRefresh
+
+		if (!isNewFetch && !isNewRefresh) {
+			if (timeback) {
+				const cached = getProfileCache(timeback)
+
+				if (cached) {
+					setState({ status: 'loaded', profile: cached })
+					onCleanup(() => {
+						cancelled = true
+					})
+
+					return
+				}
+			}
+			return
+		}
+
+		if (timeback && !force) {
+			const cached = getProfileCache(timeback)
+
+			if (cached) {
+				setState({ status: 'loaded', profile: cached })
+				lastHandledFetchNonce = fetchN
+				onCleanup(() => {
+					cancelled = true
+				})
+
+				return
+			}
+		}
+
+		setState({ status: 'loading' })
+
+		void (async () => {
+			try {
+				if (!timeback) {
+					return
+				}
+
+				lastHandledFetchNonce = fetchN
+				lastHandledRefreshNonce = refreshN
+
+				const profile = await fetchProfileOnce(timeback, force)
+
+				if (cancelled) {
+					return
+				}
+
+				setState({ status: 'loaded', profile })
+			} catch (err) {
+				if (!cancelled) {
+					setState({
+						status: 'error',
+						message: err instanceof Error ? err.message : 'Failed to fetch profile',
+					})
+				}
+			}
+		})()
+
+		onCleanup(() => {
+			cancelled = true
+		})
+	})
+
+	return {
+		get state() {
+			return state()
+		},
+		get canFetch() {
+			return canFetch()
+		},
+		fetchProfile,
+		refresh,
+	}
+}

package/dist/client/adapters/solid/primitives/createTimebackVerification.d.ts

@@ -0,0 +1,36 @@
+/**
+ * createTimebackVerification
+ *
+ * Solid primitive 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 { CreateTimebackVerificationOptions, CreateTimebackVerificationResult } from '../types';
+/**
+ * Verify the current user against Timeback.
+ *
+ * Runs automatically once the Timeback client is available, and
+ * provides a `refresh()` method to retry.
+ *
+ * @param options - Options
+ * @param options.enabled - If false, does nothing and stays in loading state.
+ * @returns Verification state and a refresh method
+ *
+ * @example
+ * ```tsx
+ * import { createTimebackVerification } from '@timeback/sdk/solid'
+ *
+ * function VerificationGate() {
+ *   const { state, refresh } = createTimebackVerification()
+ *
+ *   return (
+ *     <Show when={state().status === 'verified'}>
+ *       <p>Verified as {state().timebackId}</p>
+ *     </Show>
+ *   )
+ * }
+ * ```
+ */
+export declare function createTimebackVerification(options?: CreateTimebackVerificationOptions): CreateTimebackVerificationResult;
+//# sourceMappingURL=createTimebackVerification.d.ts.map

package/dist/client/adapters/solid/primitives/createTimebackVerification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createTimebackVerification.d.ts","sourceRoot":"","sources":["../../../../../src/client/adapters/solid/primitives/createTimebackVerification.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,OAAO,KAAK,EACX,iCAAiC,EACjC,gCAAgC,EAEhC,MAAM,UAAU,CAAA;AAcjB;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,0BAA0B,CACzC,OAAO,GAAE,iCAAsC,GAC7C,gCAAgC,CAwElC"}

package/dist/client/adapters/solid/primitives/createTimebackVerification.ts

@@ -0,0 +1,133 @@
+/**
+ * createTimebackVerification
+ *
+ * Solid primitive 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 { createEffect, createSignal, onCleanup } from 'solid-js'
+
+import { getVerifyCache, verifyOnce } from '../../../lib/user-cache'
+import { useTimeback } from '../context'
+
+import type { TimebackVerifyResult } from '../../../../shared/types'
+import type {
+	CreateTimebackVerificationOptions,
+	CreateTimebackVerificationResult,
+	TimebackVerificationState,
+} from '../types'
+
+/**
+ * Convert a verify result into a hook-friendly state machine.
+ *
+ * @param result - Raw verify result from the SDK client
+ * @returns Mapped verification state
+ */
+function toState(result: TimebackVerifyResult): TimebackVerificationState {
+	return result.verified
+		? { status: 'verified', timebackId: result.timebackId }
+		: { status: 'unverified' }
+}
+
+/**
+ * Verify the current user against Timeback.
+ *
+ * Runs automatically once the Timeback client is available, and
+ * provides a `refresh()` method to retry.
+ *
+ * @param options - Options
+ * @param options.enabled - If false, does nothing and stays in loading state.
+ * @returns Verification state and a refresh method
+ *
+ * @example
+ * ```tsx
+ * import { createTimebackVerification } from '@timeback/sdk/solid'
+ *
+ * function VerificationGate() {
+ *   const { state, refresh } = createTimebackVerification()
+ *
+ *   return (
+ *     <Show when={state().status === 'verified'}>
+ *       <p>Verified as {state().timebackId}</p>
+ *     </Show>
+ *   )
+ * }
+ * ```
+ */
+export function createTimebackVerification(
+	options: CreateTimebackVerificationOptions = {},
+): CreateTimebackVerificationResult {
+	const enabled = options.enabled ?? true
+	const timeback = useTimeback()
+
+	const [state, setState] = createSignal<TimebackVerificationState>({ status: 'loading' })
+	const [refreshNonce, setRefreshNonce] = createSignal(0)
+
+	const refresh = () => {
+		if (!enabled) return
+		setRefreshNonce(n => n + 1)
+	}
+
+	let lastHandledRefreshNonce = 0
+
+	createEffect(() => {
+		if (!enabled) return
+
+		const nonce = refreshNonce()
+		const client = timeback
+
+		let cancelled = false
+		const force = nonce > lastHandledRefreshNonce
+
+		if (client && !force) {
+			const cached = getVerifyCache(client)
+
+			if (cached) {
+				setState(toState(cached))
+				onCleanup(() => {
+					cancelled = true
+				})
+				return
+			}
+		}
+
+		setState({ status: 'loading' })
+
+		void (async () => {
+			try {
+				if (!client) return
+
+				if (force) {
+					lastHandledRefreshNonce = nonce
+				}
+
+				const result = await verifyOnce(client, force)
+
+				if (cancelled) return
+
+				setState(toState(result))
+			} catch (err) {
+				if (!cancelled) {
+					setState({
+						status: 'error',
+						message:
+							err instanceof Error ? err.message : 'Failed to verify Timeback user',
+					})
+				}
+			}
+		})()
+
+		onCleanup(() => {
+			cancelled = true
+		})
+	})
+
+	return {
+		get state() {
+			return state()
+		},
+		refresh,
+	}
+}

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

@@ -0,0 +1,86 @@
+/**
+ * Solid Types
+ *
+ * Types for Solid-specific primitives.
+ */
+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;
+};
+/**
+ * Options for createTimebackVerification.
+ */
+export interface CreateTimebackVerificationOptions {
+    /**
+     * If false, does nothing and stays in loading state.
+     *
+     * @default true
+     */
+    enabled?: boolean;
+}
+/**
+ * Return value of createTimebackVerification.
+ */
+export interface CreateTimebackVerificationResult {
+    /** Current verification state */
+    state: TimebackVerificationState;
+    /** Force a re-verification. No-op if not enabled. */
+    refresh: () => void;
+}
+/**
+ * Options for createTimebackProfile.
+ */
+export interface CreateTimebackProfileOptions {
+    /**
+     * If false, does nothing and stays in idle state.
+     *
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * If true, automatically fetch the profile once the user is verified.
+     * If false, you must call `fetchProfile()` manually.
+     *
+     * @default false
+     */
+    auto?: boolean;
+}
+/**
+ * Return value of createTimebackProfile.
+ */
+export interface CreateTimebackProfileResult {
+    /** Current profile state */
+    state: TimebackProfileState;
+    /** Whether the profile can be fetched (user is verified and client is ready) */
+    canFetch: boolean;
+    /** Manually trigger a profile fetch. No-op if canFetch is false. */
+    fetchProfile: () => void;
+    /** Force a re-fetch even if already loaded. No-op if canFetch is false. */
+    refresh: () => void;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/client/adapters/solid/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;AAEvC;;GAEG;AACH,MAAM,WAAW,iCAAiC;IACjD;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,gCAAgC;IAChD,iCAAiC;IACjC,KAAK,EAAE,yBAAyB,CAAA;IAEhC,qDAAqD;IACrD,OAAO,EAAE,MAAM,IAAI,CAAA;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC5C;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IAEjB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,OAAO,CAAA;CACd;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC3C,4BAA4B;IAC5B,KAAK,EAAE,oBAAoB,CAAA;IAE3B,gFAAgF;IAChF,QAAQ,EAAE,OAAO,CAAA;IAEjB,oEAAoE;IACpE,YAAY,EAAE,MAAM,IAAI,CAAA;IAExB,2EAA2E;IAC3E,OAAO,EAAE,MAAM,IAAI,CAAA;CACnB"}

package/dist/client/adapters/solid/types.ts

@@ -0,0 +1,85 @@
+/**
+ * Solid Types
+ *
+ * Types for Solid-specific primitives.
+ */
+
+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 }
+
+/**
+ * Options for createTimebackVerification.
+ */
+export interface CreateTimebackVerificationOptions {
+	/**
+	 * If false, does nothing and stays in loading state.
+	 *
+	 * @default true
+	 */
+	enabled?: boolean
+}
+
+/**
+ * Return value of createTimebackVerification.
+ */
+export interface CreateTimebackVerificationResult {
+	/** Current verification state */
+	state: TimebackVerificationState
+
+	/** Force a re-verification. No-op if not enabled. */
+	refresh: () => void
+}
+
+/**
+ * Options for createTimebackProfile.
+ */
+export interface CreateTimebackProfileOptions {
+	/**
+	 * If false, does nothing and stays in idle state.
+	 *
+	 * @default true
+	 */
+	enabled?: boolean
+
+	/**
+	 * If true, automatically fetch the profile once the user is verified.
+	 * If false, you must call `fetchProfile()` manually.
+	 *
+	 * @default false
+	 */
+	auto?: boolean
+}
+
+/**
+ * Return value of createTimebackProfile.
+ */
+export interface CreateTimebackProfileResult {
+	/** Current profile state */
+	state: TimebackProfileState
+
+	/** Whether the profile can be fetched (user is verified and client is ready) */
+	canFetch: boolean
+
+	/** Manually trigger a profile fetch. No-op if canFetch is false. */
+	fetchProfile: () => void
+
+	/** Force a re-fetch even if already loaded. No-op if canFetch is false. */
+	refresh: () => void
+}

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

@@ -30,7 +30,8 @@
  */
 export { Activity, createClient, TimebackClient } from '@timeback/sdk/client';
 export type { ActivityMetrics, ActivityParams, TimebackIdentity } from '@timeback/sdk/client';
-export { initTimeback, timeback } from './stores';
+export { fetchTimebackProfile, initTimeback, refreshTimebackProfile, refreshTimebackVerification, timeback, timebackProfile, timebackProfileCanFetch, timebackVerification, } from './stores';
+export type { TimebackProfileState, TimebackVerificationState } from './stores';
 export { default as SignInButton } from './SignInButton.svelte';
 export type { SignInButtonProps } from './SignInButton.svelte';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/client/adapters/svelte/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC7E,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAG7F,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAGjD,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAC/D,YAAY,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/client/adapters/svelte/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC7E,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAG7F,OAAO,EACN,oBAAoB,EACpB,YAAY,EACZ,sBAAsB,EACtB,2BAA2B,EAC3B,QAAQ,EACR,eAAe,EACf,uBAAuB,EACvB,oBAAoB,GACpB,MAAM,UAAU,CAAA;AACjB,YAAY,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,UAAU,CAAA;AAG/E,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAC/D,YAAY,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/client/adapters/svelte/index.ts

@@ -29,12 +29,21 @@
  * ```
  */
 
-// Re-export from timeback/client for convenience
 export { Activity, createClient, TimebackClient } from '@timeback/sdk/client'
 export type { ActivityMetrics, ActivityParams, TimebackIdentity } from '@timeback/sdk/client'
 
 // Svelte-specific
-export { initTimeback, timeback } from './stores'
+export {
+	fetchTimebackProfile,
+	initTimeback,
+	refreshTimebackProfile,
+	refreshTimebackVerification,
+	timeback,
+	timebackProfile,
+	timebackProfileCanFetch,
+	timebackVerification,
+} from './stores'
+export type { TimebackProfileState, TimebackVerificationState } from './stores'
 
 // Components
 export { default as SignInButton } from './SignInButton.svelte'

package/dist/client/adapters/svelte/{stores.d.ts → stores/client.d.ts}

@@ -1,17 +1,20 @@
 /**
- * Svelte Stores
+ * Timeback Client Store
  *
- * Svelte stores for Timeback SDK reactivity.
+ * Core Svelte store for the Timeback client singleton.
  */
 import { TimebackClient } from '@timeback/sdk/client';
+import type { Readable } from 'svelte/store';
 /**
- * Minimal Svelte-compatible store interface.
+ * Internal client store.
+ */
+export declare const clientStore: import("svelte/store").Writable<TimebackClient | undefined>;
+/**
+ * Get the current client instance (for internal use by other stores).
  *
- * This allows the SDK to work without a direct Svelte dependency.
+ * @returns Current client instance or undefined
  */
-interface Readable<T> {
-    subscribe: (run: (value: T) => void) => () => void;
-}
+export declare function getClientInstance(): TimebackClient | undefined;
 /**
  * Initialize the Timeback client.
  *
@@ -61,5 +64,4 @@ export declare function initTimeback(client?: TimebackClient): void;
  * ```
  */
 export declare const timeback: Readable<TimebackClient | undefined>;
-export {};
-//# sourceMappingURL=stores.d.ts.map
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../../../src/client/adapters/svelte/stores/client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAErD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AAyB5C;;GAEG;AACH,eAAO,MAAM,WAAW,6DAAkD,CAAA;AAE1E;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,GAAG,SAAS,CAE9D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,IAAI,CAQ1D;AASD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,QAAQ,EAAE,QAAQ,CAAC,cAAc,GAAG,SAAS,CAAe,CAAA"}