@startsimpli/hooks 0.4.50 → 0.4.51

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@startsimpli/hooks",
3
- "version": "0.4.50",
3
+ "version": "0.4.51",
4
4
  "description": "Shared React hooks for StartSimpli apps",
5
5
  "license": "MIT",
6
6
  "homepage": "https://startsimpli.com",
@@ -34,7 +34,7 @@
34
34
  "@tanstack/react-query": ">=5.0.0",
35
35
  "react": ">=18.0.0",
36
36
  "react-native": ">=0.74.0",
37
- "@startsimpli/api": "^0.5.72"
37
+ "@startsimpli/api": "^0.5.73"
38
38
  },
39
39
  "peerDependenciesMeta": {
40
40
  "@tanstack/react-query": {
@@ -57,7 +57,7 @@
57
57
  "tsup": "^8.5.1",
58
58
  "typescript": "^6.0.3",
59
59
  "vitest": "^4.1.5",
60
- "@startsimpli/api": "0.5.72"
60
+ "@startsimpli/api": "0.5.73"
61
61
  },
62
62
  "scripts": {
63
63
  "build": "tsup",
@@ -0,0 +1,37 @@
1
+ import { describe, it, expect, vi } from 'vitest'
2
+ import { renderHook, waitFor } from '@testing-library/react'
3
+ import { useBuilderAccess, type BuilderAccessSource } from '../useBuilderAccess'
4
+
5
+ const src = (check: BuilderAccessSource['check']): BuilderAccessSource => ({ check })
6
+
7
+ describe('useBuilderAccess', () => {
8
+ it('loads, then reports allowed', async () => {
9
+ const { result } = renderHook(() => useBuilderAccess(src(vi.fn().mockResolvedValue({ allowed: true }))))
10
+ expect(result.current.status).toBe('loading')
11
+ await waitFor(() => expect(result.current.status).toBe('ready'))
12
+ expect(result.current.allowed).toBe(true)
13
+ })
14
+
15
+ it('reports the server reason and message when refused', async () => {
16
+ const v = { allowed: false as const, reason: 'limit_reached' as const, message: 'Used 3.' }
17
+ const { result } = renderHook(() => useBuilderAccess(src(vi.fn().mockResolvedValue(v))))
18
+ await waitFor(() => expect(result.current.status).toBe('ready'))
19
+ expect(result.current.allowed).toBe(false)
20
+ expect(result.current.reason).toBe('limit_reached')
21
+ expect(result.current.message).toBe('Used 3.')
22
+ })
23
+
24
+ it('an unexpected failure is an error, never a silent "no"', async () => {
25
+ const { result } = renderHook(() => useBuilderAccess(src(vi.fn().mockRejectedValue(new Error('down')))))
26
+ await waitFor(() => expect(result.current.status).toBe('error'))
27
+ expect(result.current.allowed).toBe(false)
28
+ expect(result.current.error).toBe('down')
29
+ })
30
+
31
+ it('enabled=false never calls the server', async () => {
32
+ const check = vi.fn()
33
+ const { result } = renderHook(() => useBuilderAccess(src(check), { enabled: false }))
34
+ expect(result.current.status).toBe('idle')
35
+ expect(check).not.toHaveBeenCalled()
36
+ })
37
+ })
@@ -0,0 +1,30 @@
1
+ /** useCreditDesigns: the patterns a credit paid for. The API is a fake. */
2
+ import { describe, it, expect, vi } from 'vitest'
3
+ import { renderHook, waitFor } from '@testing-library/react'
4
+ import { useCreditDesigns } from '../useCreditDesigns'
5
+
6
+ describe('useCreditDesigns', () => {
7
+ it('says which pattern ids a credit paid for (number or string ids)', async () => {
8
+ const source = { getDesigns: vi.fn().mockResolvedValue({ refs: ['12', '40'] }) }
9
+ const { result } = renderHook(() => useCreditDesigns(source))
10
+ expect(result.current.loaded).toBe(false)
11
+ await waitFor(() => expect(result.current.loaded).toBe(true))
12
+ expect(result.current.isCreditDesign(12)).toBe(true)
13
+ expect(result.current.isCreditDesign('40')).toBe(true)
14
+ expect(result.current.isCreditDesign(7)).toBe(false)
15
+ expect(result.current.isCreditDesign(null)).toBe(false)
16
+ })
17
+
18
+ it('a failed read means no credit designs, not an error screen', async () => {
19
+ const source = { getDesigns: vi.fn().mockRejectedValue(new Error('409')) }
20
+ const { result } = renderHook(() => useCreditDesigns(source))
21
+ await waitFor(() => expect(result.current.loaded).toBe(true))
22
+ expect(result.current.isCreditDesign(12)).toBe(false)
23
+ })
24
+
25
+ it('does not call the server when disabled', () => {
26
+ const source = { getDesigns: vi.fn() }
27
+ renderHook(() => useCreditDesigns(source, { enabled: false }))
28
+ expect(source.getDesigns).not.toHaveBeenCalled()
29
+ })
30
+ })
@@ -0,0 +1,109 @@
1
+ /** usePatternCredits: balance/offers/history load, flag-off, buy, sync. The API is a fake. */
2
+ import { describe, it, expect, vi } from 'vitest'
3
+ import { renderHook, act, waitFor } from '@testing-library/react'
4
+ import { usePatternCredits, type PatternCreditsSource } from '../usePatternCredits'
5
+
6
+ const SUMMARY = {
7
+ balance: 2,
8
+ unit: 'pattern',
9
+ offers: [{ id: 'o1', slug: 'single', name: 'One', credits: 1, price: '4.99', currency: 'usd', compareAt: '', featured: false }],
10
+ history: [{ id: 'h1', entryType: 'grant', quantity: 5, externalRef: '', reason: 'Bought', createdAt: '2026-11-09T00:00:00Z' }],
11
+ }
12
+
13
+ function fakeApi(over: Partial<PatternCreditsSource> = {}) {
14
+ const api: PatternCreditsSource = {
15
+ getSummary: vi.fn().mockResolvedValue(SUMMARY),
16
+ checkout: vi.fn().mockResolvedValue({ url: 'https://checkout.stripe.com/x', sessionId: 'cs_1' }),
17
+ sync: vi.fn().mockResolvedValue({ granted: true, balance: 7 }),
18
+ ...over,
19
+ }
20
+ return api
21
+ }
22
+
23
+ describe('usePatternCredits', () => {
24
+ it('starts loading, then exposes balance, offers and history', async () => {
25
+ const { result } = renderHook(() => usePatternCredits(fakeApi()))
26
+ expect(result.current.status).toBe('loading')
27
+ await waitFor(() => expect(result.current.status).toBe('ready'))
28
+ expect(result.current.balance).toBe(2)
29
+ expect(result.current.offers).toHaveLength(1)
30
+ expect(result.current.history[0].entryType).toBe('grant')
31
+ })
32
+
33
+ it('is "disabled" when the server says the sale is off, with nothing to show', async () => {
34
+ const api = fakeApi({ getSummary: vi.fn().mockRejectedValue({ status: 409, code: 'pattern_credits_disabled' }) })
35
+ const { result } = renderHook(() => usePatternCredits(api))
36
+ await waitFor(() => expect(result.current.status).toBe('disabled'))
37
+ expect(result.current.offers).toEqual([])
38
+ expect(result.current.error).toBeNull()
39
+ })
40
+
41
+ it('reports other failures as an error with a message', async () => {
42
+ const api = fakeApi({ getSummary: vi.fn().mockRejectedValue(new Error('boom')) })
43
+ const { result } = renderHook(() => usePatternCredits(api))
44
+ await waitFor(() => expect(result.current.status).toBe('error'))
45
+ expect(result.current.error).toBe('boom')
46
+ })
47
+
48
+ it('does not call the server when enabled is false', async () => {
49
+ const api = fakeApi()
50
+ const { result } = renderHook(() => usePatternCredits(api, { enabled: false }))
51
+ expect(result.current.status).toBe('disabled')
52
+ expect(api.getSummary).not.toHaveBeenCalled()
53
+ })
54
+
55
+ it('buy starts checkout for the offer and sends the browser to the hosted page', async () => {
56
+ const api = fakeApi()
57
+ const go = vi.fn()
58
+ const { result } = renderHook(() =>
59
+ usePatternCredits(api, { returnUrls: { successUrl: 's', cancelUrl: 'c' }, navigate: go }))
60
+ await waitFor(() => expect(result.current.status).toBe('ready'))
61
+ await act(async () => { await result.current.buy('o1') })
62
+ expect(api.checkout).toHaveBeenCalledWith('o1', { successUrl: 's', cancelUrl: 'c' })
63
+ expect(go).toHaveBeenCalledWith('https://checkout.stripe.com/x')
64
+ })
65
+
66
+ it('buy failing sets error and never navigates', async () => {
67
+ const api = fakeApi({ checkout: vi.fn().mockRejectedValue(new Error('nope')) })
68
+ const go = vi.fn()
69
+ const { result } = renderHook(() =>
70
+ usePatternCredits(api, { returnUrls: { successUrl: 's', cancelUrl: 'c' }, navigate: go }))
71
+ await waitFor(() => expect(result.current.status).toBe('ready'))
72
+ await act(async () => { await result.current.buy('o1') })
73
+ expect(go).not.toHaveBeenCalled()
74
+ expect(result.current.error).toBe('nope')
75
+ expect(result.current.buying).toBeNull()
76
+ })
77
+
78
+ it('sync grants a paid session and shows the new balance', async () => {
79
+ const api = fakeApi({
80
+ getSummary: vi.fn().mockResolvedValueOnce(SUMMARY).mockResolvedValue({ ...SUMMARY, balance: 7 }),
81
+ })
82
+ const { result } = renderHook(() => usePatternCredits(api))
83
+ await waitFor(() => expect(result.current.status).toBe('ready'))
84
+ await act(async () => { await result.current.sync('cs_1') })
85
+ expect(api.sync).toHaveBeenCalledWith('cs_1')
86
+ expect(result.current.balance).toBe(7)
87
+ })
88
+
89
+ it('sync that fails is surfaced, balance untouched', async () => {
90
+ const api = fakeApi({ sync: vi.fn().mockRejectedValue(new Error('403')) })
91
+ const { result } = renderHook(() => usePatternCredits(api))
92
+ await waitFor(() => expect(result.current.status).toBe('ready'))
93
+ await act(async () => { await result.current.sync('cs_x').catch(() => {}) })
94
+ expect(result.current.error).toBe('403')
95
+ expect(result.current.balance).toBe(2)
96
+ })
97
+
98
+ it('resolves a lazy returnUrls function at buy time, not at render (safe on the server)', async () => {
99
+ const api = fakeApi()
100
+ const go = vi.fn()
101
+ const returnUrls = vi.fn(() => ({ successUrl: 'https://app/s', cancelUrl: 'https://app/c' }))
102
+ const { result } = renderHook(() => usePatternCredits(api, { returnUrls, navigate: go }))
103
+ await waitFor(() => expect(result.current.status).toBe('ready'))
104
+ expect(returnUrls).not.toHaveBeenCalled()
105
+ await act(async () => { await result.current.buy('o1') })
106
+ expect(returnUrls).toHaveBeenCalledTimes(1)
107
+ expect(api.checkout).toHaveBeenCalledWith('o1', { successUrl: 'https://app/s', cancelUrl: 'https://app/c' })
108
+ })
109
+ })
package/src/index.ts CHANGED
@@ -68,6 +68,23 @@ export type {
68
68
  } from './useCSV'
69
69
  export { useAsyncOptions } from './useAsyncOptions'
70
70
 
71
+ // Builder access: the server's verdict on who may make a design
72
+ export { useBuilderAccess } from './useBuilderAccess'
73
+ export type { BuilderAccessSource, BuilderAccessStatus, UseBuilderAccessResult } from './useBuilderAccess'
74
+
75
+ // Pattern credits: balance, offers, history, buy, sync
76
+ export { usePatternCredits } from './usePatternCredits'
77
+ export type {
78
+ PatternCreditsSource,
79
+ PatternCreditsStatus,
80
+ UsePatternCreditsOptions,
81
+ UsePatternCreditsResult,
82
+ } from './usePatternCredits'
83
+
84
+ // Pattern credits: which designs a credit paid for (free revisions, always saveable)
85
+ export { useCreditDesigns } from './useCreditDesigns'
86
+ export type { CreditDesignsSource, UseCreditDesignsResult } from './useCreditDesigns'
87
+
71
88
  // Upload state machine (crochet_patterns-llmj; provisional)
72
89
  export { useUpload } from './useUpload'
73
90
  export type { FileUploader, UploadItem, UploadStatus, UseUploadOptions, UseUploadResult } from './useUpload'
@@ -0,0 +1,70 @@
1
+ 'use client'
2
+
3
+ /**
4
+ * useBuilderAccess: may this person make a design? The answer is the server's
5
+ * (BuilderAccessApi, from apps/builder/access.py); this hook only holds it.
6
+ * `refresh` re-asks, e.g. after a plan change or a bought credit.
7
+ */
8
+
9
+ import { useCallback, useEffect, useRef, useState } from 'react'
10
+ import type { BuilderAccess, BuilderAccessReason } from '@startsimpli/api'
11
+
12
+ export interface BuilderAccessSource {
13
+ check(): Promise<BuilderAccess>
14
+ }
15
+
16
+ export type BuilderAccessStatus = 'idle' | 'loading' | 'ready' | 'error'
17
+
18
+ export interface UseBuilderAccessResult {
19
+ status: BuilderAccessStatus
20
+ allowed: boolean
21
+ reason: BuilderAccessReason | null
22
+ message: string
23
+ error: string | null
24
+ refresh: () => Promise<void>
25
+ }
26
+
27
+ export function useBuilderAccess(
28
+ api: BuilderAccessSource,
29
+ options: { enabled?: boolean } = {},
30
+ ): UseBuilderAccessResult {
31
+ const { enabled = true } = options
32
+ const [status, setStatus] = useState<BuilderAccessStatus>(enabled ? 'loading' : 'idle')
33
+ const [verdict, setVerdict] = useState<BuilderAccess | null>(null)
34
+ const [error, setError] = useState<string | null>(null)
35
+ const alive = useRef(true)
36
+ useEffect(() => {
37
+ alive.current = true
38
+ return () => { alive.current = false }
39
+ }, [])
40
+
41
+ const load = useCallback(async () => {
42
+ try {
43
+ const v = await api.check()
44
+ if (!alive.current) return
45
+ setVerdict(v)
46
+ setError(null)
47
+ setStatus('ready')
48
+ } catch (e) {
49
+ if (!alive.current) return
50
+ setVerdict(null)
51
+ setError(e instanceof Error ? e.message : String((e as { message?: unknown })?.message ?? 'Could not check access.'))
52
+ setStatus('error')
53
+ }
54
+ }, [api])
55
+
56
+ useEffect(() => {
57
+ if (!enabled) { setStatus('idle'); return }
58
+ setStatus('loading')
59
+ void load()
60
+ }, [enabled, load])
61
+
62
+ return {
63
+ status,
64
+ allowed: verdict?.allowed === true,
65
+ reason: verdict && !verdict.allowed ? verdict.reason : null,
66
+ message: verdict && !verdict.allowed ? verdict.message : '',
67
+ error,
68
+ refresh: load,
69
+ }
70
+ }
@@ -0,0 +1,39 @@
1
+ 'use client'
2
+
3
+ /**
4
+ * useCreditDesigns: which patterns a pattern credit paid for. Such a design has free revisions (refine/edit/chat need no plan) and is
5
+ * always saveable (it never counts toward the free saved cap). The server enforces both; this only lets a screen say so.
6
+ * A failed or disabled read is "no designs": the screen then shows nothing extra rather than a wrong promise.
7
+ */
8
+
9
+ import { useEffect, useState } from 'react'
10
+
11
+ export interface CreditDesignsSource {
12
+ getDesigns(): Promise<{ refs: string[] }>
13
+ }
14
+
15
+ export interface UseCreditDesignsResult {
16
+ loaded: boolean
17
+ refs: ReadonlySet<string>
18
+ /** True when a credit paid for this pattern id. */
19
+ isCreditDesign: (patternId: string | number | null | undefined) => boolean
20
+ }
21
+
22
+ const NONE: ReadonlySet<string> = new Set()
23
+
24
+ export function useCreditDesigns(source: CreditDesignsSource, options: { enabled?: boolean } = {}): UseCreditDesignsResult {
25
+ const enabled = options.enabled ?? true
26
+ const [state, setState] = useState<{ loaded: boolean; refs: ReadonlySet<string> }>({ loaded: false, refs: NONE })
27
+
28
+ useEffect(() => {
29
+ if (!enabled) return
30
+ let live = true
31
+ source.getDesigns().then(
32
+ (r) => { if (live) setState({ loaded: true, refs: new Set((r.refs ?? []).map(String)) }) },
33
+ () => { if (live) setState({ loaded: true, refs: NONE }) },
34
+ )
35
+ return () => { live = false }
36
+ }, [source, enabled])
37
+
38
+ return { ...state, isCreditDesign: (id) => id != null && state.refs.has(String(id)) }
39
+ }
@@ -0,0 +1,147 @@
1
+ 'use client'
2
+
3
+ /**
4
+ * usePatternCredits: the signed-in person's pattern-credit balance, the packs
5
+ * on sale and their history, plus buy (hosted Checkout) and sync (grant a paid
6
+ * session on the return page).
7
+ *
8
+ * Plain React state, no query client, so any app can use it. `status` is
9
+ * "disabled" when the sale flag is off (server 409 `pattern_credits_disabled`)
10
+ * or `enabled` is false: render nothing new then.
11
+ */
12
+
13
+ import { useCallback, useEffect, useRef, useState } from 'react'
14
+ import type {
15
+ PatternCreditCheckout,
16
+ PatternCreditHistoryEntry,
17
+ PatternCreditOffer,
18
+ PatternCreditsSummary,
19
+ PatternCreditsSyncResult,
20
+ } from '@startsimpli/api'
21
+
22
+ /** What the hook needs from `PatternCreditsApi`. */
23
+ export interface PatternCreditsSource {
24
+ getSummary(): Promise<PatternCreditsSummary>
25
+ checkout(offerId: string, urls: { successUrl: string; cancelUrl: string }): Promise<PatternCreditCheckout>
26
+ sync(sessionId: string): Promise<PatternCreditsSyncResult>
27
+ }
28
+
29
+ export type PatternCreditsStatus = 'loading' | 'ready' | 'error' | 'disabled'
30
+
31
+ type ReturnUrls = { successUrl: string; cancelUrl: string }
32
+
33
+ export interface UsePatternCreditsOptions {
34
+ /** False: never call the server, status stays "disabled". Default true. */
35
+ enabled?: boolean
36
+ /** Where Stripe sends the browser after paying / cancelling. Required to `buy`. A function is called at buy time, so it can read `window` without an SSR guard. */
37
+ returnUrls?: ReturnUrls | (() => ReturnUrls)
38
+ /** Default: `window.location.assign`. */
39
+ navigate?: (url: string) => void
40
+ }
41
+
42
+ export interface UsePatternCreditsResult {
43
+ status: PatternCreditsStatus
44
+ balance: number
45
+ offers: PatternCreditOffer[]
46
+ history: PatternCreditHistoryEntry[]
47
+ error: string | null
48
+ /** The offer id whose checkout is being opened, else null. */
49
+ buying: string | null
50
+ refresh: () => Promise<void>
51
+ buy: (offerId: string) => Promise<void>
52
+ sync: (sessionId: string) => Promise<PatternCreditsSyncResult>
53
+ }
54
+
55
+ const messageOf = (e: unknown): string =>
56
+ e instanceof Error ? e.message : typeof (e as { message?: unknown })?.message === 'string'
57
+ ? String((e as { message: string }).message)
58
+ : 'Something went wrong. Please try again.'
59
+
60
+ const isDisabled = (e: unknown): boolean => {
61
+ const err = e as { status?: number; code?: string; details?: { code?: string } } | null
62
+ return err?.status === 409 && (err.code ?? err.details?.code) === 'pattern_credits_disabled'
63
+ }
64
+
65
+ export function usePatternCredits(
66
+ api: PatternCreditsSource,
67
+ options: UsePatternCreditsOptions = {},
68
+ ): UsePatternCreditsResult {
69
+ const { enabled = true, returnUrls, navigate } = options
70
+ const [status, setStatus] = useState<PatternCreditsStatus>(enabled ? 'loading' : 'disabled')
71
+ const [summary, setSummary] = useState<PatternCreditsSummary | null>(null)
72
+ const [error, setError] = useState<string | null>(null)
73
+ const [buying, setBuying] = useState<string | null>(null)
74
+ const alive = useRef(true)
75
+ useEffect(() => {
76
+ alive.current = true
77
+ return () => { alive.current = false }
78
+ }, [])
79
+
80
+ const load = useCallback(async () => {
81
+ try {
82
+ const next = await api.getSummary()
83
+ if (!alive.current) return
84
+ setSummary(next)
85
+ setError(null)
86
+ setStatus('ready')
87
+ } catch (e) {
88
+ if (!alive.current) return
89
+ if (isDisabled(e)) {
90
+ setSummary(null)
91
+ setError(null)
92
+ setStatus('disabled')
93
+ } else {
94
+ setError(messageOf(e))
95
+ setStatus('error')
96
+ }
97
+ }
98
+ }, [api])
99
+
100
+ useEffect(() => {
101
+ if (!enabled) { setStatus('disabled'); return }
102
+ setStatus('loading')
103
+ void load()
104
+ }, [enabled, load])
105
+
106
+ const buy = useCallback(async (offerId: string) => {
107
+ if (!returnUrls) { setError('Checkout is not set up here.'); return }
108
+ setError(null)
109
+ setBuying(offerId)
110
+ try {
111
+ const urls = typeof returnUrls === 'function' ? returnUrls() : returnUrls
112
+ const { url } = await api.checkout(offerId, urls)
113
+ if (!url) throw new Error('Unable to start checkout. Please try again.')
114
+ ;(navigate ?? ((u: string) => window.location.assign(u)))(url)
115
+ // Left "buying" on purpose: the page is unloading, the button stays off.
116
+ } catch (e) {
117
+ if (alive.current) { setError(messageOf(e)); setBuying(null) }
118
+ }
119
+ }, [api, returnUrls, navigate])
120
+
121
+ const sync = useCallback(async (sessionId: string) => {
122
+ try {
123
+ const result = await api.sync(sessionId)
124
+ if (alive.current) {
125
+ setSummary((s) => (s ? { ...s, balance: result.balance } : s))
126
+ setError(null)
127
+ }
128
+ void load()
129
+ return result
130
+ } catch (e) {
131
+ if (alive.current) setError(messageOf(e))
132
+ throw e
133
+ }
134
+ }, [api, load])
135
+
136
+ return {
137
+ status,
138
+ balance: summary?.balance ?? 0,
139
+ offers: summary?.offers ?? [],
140
+ history: summary?.history ?? [],
141
+ error,
142
+ buying,
143
+ refresh: load,
144
+ buy,
145
+ sync,
146
+ }
147
+ }