@reopt-ai/brandapp-sdk 3.3.0 → 3.5.0

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.
Files changed (104) hide show
  1. package/CHANGELOG.md +115 -0
  2. package/README.md +10 -1
  3. package/dist/abort--nOBFN4M.js +50 -0
  4. package/dist/ai/index.d.ts +2 -314
  5. package/dist/ai/index.js +3 -8
  6. package/dist/ai-provider/index.d.ts +79 -163
  7. package/dist/ai-provider/index.js +752 -685
  8. package/dist/auth/index.d.ts +27 -27
  9. package/dist/auth/index.js +41 -34
  10. package/dist/better-auth/client.d.ts +6 -5
  11. package/dist/better-auth/client.js +28 -5
  12. package/dist/better-auth/index.d.ts +19 -17
  13. package/dist/better-auth/index.js +180 -144
  14. package/dist/client-61ldOHMz.js +503 -0
  15. package/dist/client-7PCoxVhZ.js +28 -0
  16. package/dist/client-B7rZQ8Zi.d.ts +272 -0
  17. package/dist/client-BGGd_cpV.d.ts +103 -0
  18. package/dist/client-BoIuyx4S.js +273 -0
  19. package/dist/client-BruP5_nU.d.ts +147 -0
  20. package/dist/client-BxtZt405.js +305 -0
  21. package/dist/client-ByN3EQdk.js +83 -0
  22. package/dist/client-CAghoGD_.js +53 -0
  23. package/dist/client-C_pHsPlj.js +81 -0
  24. package/dist/client-D0eBxh8j.d.ts +284 -0
  25. package/dist/client-D6gs61w8.d.ts +53 -0
  26. package/dist/client-DDw5yz_h.d.ts +53 -0
  27. package/dist/client-Dxg8_DIH.d.ts +71 -0
  28. package/dist/client-aMR4CRB8.d.ts +211 -0
  29. package/dist/client-lk6wBu_0.d.ts +48 -0
  30. package/dist/client-wEVKLdly.js +55 -0
  31. package/dist/client-zF1RG2uA.js +86 -0
  32. package/dist/cms/index.d.ts +52 -108
  33. package/dist/cms/index.js +103 -86
  34. package/dist/config-CRytOPPl.d.ts +394 -0
  35. package/dist/config-aml9oQpX.js +487 -0
  36. package/dist/dev/index.d.ts +2 -528
  37. package/dist/dev/index.js +3047 -2967
  38. package/dist/eav/coerce.d.ts +3 -1
  39. package/dist/eav/coerce.js +72 -46
  40. package/dist/eav/index.d.ts +72 -100
  41. package/dist/eav/index.js +158 -126
  42. package/dist/eav/migrate.d.ts +112 -109
  43. package/dist/eav/migrate.js +230 -196
  44. package/dist/eav/schema.d.ts +111 -150
  45. package/dist/eav/schema.js +624 -603
  46. package/dist/encoding-Bwfm3iaE.js +21 -0
  47. package/dist/{errors-BjDFIyA6.d.ts → errors-CRCcErNC.d.ts} +55 -53
  48. package/dist/feedback/index.d.ts +2 -132
  49. package/dist/feedback/index.js +3 -6
  50. package/dist/files/index.d.ts +14 -14
  51. package/dist/files/index.js +41 -25
  52. package/dist/http-client-BZc2mngq.js +386 -0
  53. package/dist/index-1j_738qk.d.ts +470 -0
  54. package/dist/index-CeOLGdyL.d.ts +169 -0
  55. package/dist/index.d.ts +6 -230
  56. package/dist/index.js +119 -71
  57. package/dist/logout/index.d.ts +56 -53
  58. package/dist/logout/index.js +232 -289
  59. package/dist/plans/index.d.ts +2 -236
  60. package/dist/plans/index.js +3 -6
  61. package/dist/push/index.d.ts +2 -79
  62. package/dist/push/index.js +3 -6
  63. package/dist/query-xWqtfkvR.js +35 -0
  64. package/dist/react/hooks.d.ts +157 -100
  65. package/dist/react/hooks.js +862 -406
  66. package/dist/sse-parser-FMjxM7sY.js +86 -0
  67. package/dist/terms/index.d.ts +3 -79
  68. package/dist/terms/index.js +3 -6
  69. package/dist/testing/index.d.ts +52 -104
  70. package/dist/testing/index.js +94 -72
  71. package/dist/types-B-SMkH6s.d.ts +26 -0
  72. package/dist/types-BXDcoJHG.d.ts +131 -0
  73. package/dist/types-BrghN2rJ.d.ts +105 -0
  74. package/dist/types-DjDRszNj.js +11 -0
  75. package/dist/webhooks/index.d.ts +77 -50
  76. package/dist/webhooks/index.js +150 -127
  77. package/docs/api-reference.md +121 -8
  78. package/docs/errors.md +19 -0
  79. package/docs/files.md +165 -7
  80. package/package.json +7 -6
  81. package/dist/chunk-2LSCQHAU.js +0 -21
  82. package/dist/chunk-4U4ZPPL4.js +0 -599
  83. package/dist/chunk-55KHY5GH.js +0 -96
  84. package/dist/chunk-C5VTRZWX.js +0 -458
  85. package/dist/chunk-F7BXBTZI.js +0 -54
  86. package/dist/chunk-FJUCWXX3.js +0 -350
  87. package/dist/chunk-H33OTQEN.js +0 -112
  88. package/dist/chunk-L4DHB36G.js +0 -75
  89. package/dist/chunk-OG7R3UAR.js +0 -105
  90. package/dist/chunk-PF24XU54.js +0 -32
  91. package/dist/chunk-QN3QD67K.js +0 -49
  92. package/dist/chunk-REIKXSMY.js +0 -7
  93. package/dist/chunk-UGBBXCZE.js +0 -157
  94. package/dist/chunk-UVT2E6KD.js +0 -81
  95. package/dist/chunk-YPLT3RFL.js +0 -63
  96. package/dist/chunk-YTKSAWV2.js +0 -463
  97. package/dist/client-BkcO-0C2.d.ts +0 -216
  98. package/dist/client-CN5_tNOC.d.ts +0 -147
  99. package/dist/client-DttyeM_h.d.ts +0 -102
  100. package/dist/config-CtxyJsDR.d.ts +0 -397
  101. package/dist/typed-client-BxOVIiMU.d.ts +0 -40
  102. package/dist/types-6E3ZLL9X.d.ts +0 -24
  103. package/dist/types-DskYLVb8.d.ts +0 -104
  104. package/dist/types-ckmDDW3N.d.ts +0 -129
@@ -1,469 +1,925 @@
1
- import { useState, useRef, useEffect, useCallback } from 'react';
2
- import { useQuery, useInfiniteQuery, useQueryClient, useMutation } from '@tanstack/react-query';
1
+ "use client";
3
2
 
4
- var hasRaf = typeof requestAnimationFrame === "function";
3
+ import { useCallback, useEffect, useRef, useState } from "react";
4
+ import { useInfiniteQuery, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
5
+
6
+ //#region src/react/use-ai-stream.ts
7
+ /**
8
+ * React hook for AI text streaming via BrandApp SDK.
9
+ *
10
+ * Uses `sdk.ai.streamWithMetadata()` internally to provide
11
+ * incremental text accumulation, abort support, and usage metadata.
12
+ *
13
+ * @example
14
+ * ```tsx
15
+ * const { text, isStreaming, generate, stop } = useAiStream(sdk);
16
+ *
17
+ * return (
18
+ * <div>
19
+ * <button onClick={() => generate({ messages: [{ role: "user", content: "Hello" }] })}>
20
+ * Generate
21
+ * </button>
22
+ * <button onClick={stop} disabled={!isStreaming}>Stop</button>
23
+ * <p>{text}</p>
24
+ * </div>
25
+ * );
26
+ * ```
27
+ */
28
+ const hasRaf = typeof requestAnimationFrame === "function";
5
29
  function useAiStream(sdk, options) {
6
- const [text, setText] = useState("");
7
- const [isStreaming, setIsStreaming] = useState(false);
8
- const [error, setError] = useState(null);
9
- const [metadata, setMetadata] = useState(null);
10
- const controllerRef = useRef(null);
11
- const optionsRef = useRef(options);
12
- const pendingTextRef = useRef("");
13
- const rafRef = useRef(null);
14
- useEffect(() => {
15
- optionsRef.current = options;
16
- }, [options]);
17
- const cancelTextFlush = useCallback(() => {
18
- if (rafRef.current !== null) {
19
- cancelAnimationFrame(rafRef.current);
20
- rafRef.current = null;
21
- }
22
- }, []);
23
- const commitText = useCallback(() => {
24
- cancelTextFlush();
25
- setText(pendingTextRef.current);
26
- }, [cancelTextFlush]);
27
- const scheduleTextFlush = useCallback(() => {
28
- if (!hasRaf) {
29
- setText(pendingTextRef.current);
30
- return;
31
- }
32
- if (rafRef.current !== null) return;
33
- rafRef.current = requestAnimationFrame(() => {
34
- rafRef.current = null;
35
- setText(pendingTextRef.current);
36
- });
37
- }, []);
38
- const stop = useCallback(() => {
39
- cancelTextFlush();
40
- controllerRef.current?.abort();
41
- controllerRef.current = null;
42
- }, [cancelTextFlush]);
43
- const reset = useCallback(() => {
44
- stop();
45
- pendingTextRef.current = "";
46
- setText("");
47
- setError(null);
48
- setMetadata(null);
49
- setIsStreaming(false);
50
- }, [stop]);
51
- useEffect(() => {
52
- return () => {
53
- cancelTextFlush();
54
- controllerRef.current?.abort();
55
- controllerRef.current = null;
56
- };
57
- }, [cancelTextFlush]);
58
- const generate = useCallback(
59
- (completionOptions) => {
60
- stop();
61
- const controller = new AbortController();
62
- controllerRef.current = controller;
63
- pendingTextRef.current = "";
64
- setText("");
65
- setError(null);
66
- setMetadata(null);
67
- setIsStreaming(true);
68
- const { textStream, metadata: metaPromise } = sdk.ai.streamWithMetadata({
69
- ...completionOptions,
70
- signal: controller.signal
71
- });
72
- (async () => {
73
- try {
74
- let accumulated = "";
75
- for await (const chunk of textStream) {
76
- if (controller.signal.aborted) break;
77
- accumulated += chunk;
78
- pendingTextRef.current = accumulated;
79
- scheduleTextFlush();
80
- optionsRef.current?.onChunk?.(chunk);
81
- }
82
- const meta = await metaPromise;
83
- if (!controller.signal.aborted) {
84
- commitText();
85
- setMetadata(meta);
86
- optionsRef.current?.onFinish?.(accumulated, meta);
87
- }
88
- } catch (err) {
89
- if (!controller.signal.aborted) {
90
- commitText();
91
- const e = err instanceof Error ? err : new Error(String(err));
92
- setError(e);
93
- optionsRef.current?.onError?.(e);
94
- }
95
- } finally {
96
- if (controllerRef.current === controller) {
97
- setIsStreaming(false);
98
- controllerRef.current = null;
99
- }
100
- }
101
- })();
102
- },
103
- [sdk, stop, scheduleTextFlush, commitText]
104
- );
105
- return { text, isStreaming, error, metadata, generate, stop, reset };
106
- }
107
- var keys = {
108
- all: ["reopt"],
109
- entities: (brandappId) => [...keys.all, "entities", brandappId],
110
- entity: (entityId) => [...keys.all, "entity", entityId],
111
- records: (entityId, query) => [...keys.all, "records", entityId, query],
112
- // Infinite lists get a DISTINCT namespace: in TanStack v5 useQuery and
113
- // useInfiniteQuery share one QueryCache keyed by queryHash, so a shared key
114
- // would collide (PaginatedResponse vs InfiniteData) if both hooks mount for
115
- // the same entity+query.
116
- recordsInfinite: (entityId, query) => [...keys.all, "recordsInfinite", entityId, query],
117
- record: (entityId, recordId) => [...keys.all, "record", entityId, recordId],
118
- recordCount: (entityId, query) => [...keys.all, "recordCount", entityId, query],
119
- // Length-3 invalidation prefixes. partialMatchKey only prefix-matches a
120
- // SHORTER key, so `keys.records(entityId)` (trailing `undefined`) fails to
121
- // match a list queried WITH a query object. These match every finite /
122
- // infinite record list + count for an entity regardless of its query object.
123
- recordsPrefix: (entityId) => [...keys.all, "records", entityId],
124
- recordsInfinitePrefix: (entityId) => [...keys.all, "recordsInfinite", entityId],
125
- recordCountPrefix: (entityId) => [...keys.all, "recordCount", entityId],
126
- aiCredits: (brandappId) => [...keys.all, "ai", "credits", brandappId],
127
- aiModels: (brandappId) => [...keys.all, "ai", "models", brandappId],
128
- aiAgents: (brandappId) => [...keys.all, "ai", "agents", brandappId],
129
- posts: (brandappId, query) => [...keys.all, "posts", brandappId, query],
130
- post: (postId) => [...keys.all, "post", postId],
131
- postGroups: (brandappId, query) => [...keys.all, "postGroups", brandappId, query],
132
- postGroup: (groupId) => [...keys.all, "postGroup", groupId],
133
- tags: (brandappId, query) => [...keys.all, "tags", brandappId, query],
134
- files: (brandappId, query) => [...keys.all, "files", brandappId, query],
135
- file: (fileId) => [...keys.all, "file", fileId]
30
+ const [text, setText] = useState("");
31
+ const [isStreaming, setIsStreaming] = useState(false);
32
+ const [error, setError] = useState(null);
33
+ const [metadata, setMetadata] = useState(null);
34
+ const controllerRef = useRef(null);
35
+ const optionsRef = useRef(options);
36
+ const pendingTextRef = useRef("");
37
+ const rafRef = useRef(null);
38
+ useEffect(() => {
39
+ optionsRef.current = options;
40
+ }, [options]);
41
+ const cancelTextFlush = useCallback(() => {
42
+ if (rafRef.current !== null) {
43
+ cancelAnimationFrame(rafRef.current);
44
+ rafRef.current = null;
45
+ }
46
+ }, []);
47
+ const commitText = useCallback(() => {
48
+ cancelTextFlush();
49
+ setText(pendingTextRef.current);
50
+ }, [cancelTextFlush]);
51
+ const scheduleTextFlush = useCallback(() => {
52
+ if (!hasRaf) {
53
+ setText(pendingTextRef.current);
54
+ return;
55
+ }
56
+ if (rafRef.current !== null) return;
57
+ rafRef.current = requestAnimationFrame(() => {
58
+ rafRef.current = null;
59
+ setText(pendingTextRef.current);
60
+ });
61
+ }, []);
62
+ const stop = useCallback(() => {
63
+ cancelTextFlush();
64
+ controllerRef.current?.abort();
65
+ controllerRef.current = null;
66
+ }, [cancelTextFlush]);
67
+ const reset = useCallback(() => {
68
+ stop();
69
+ pendingTextRef.current = "";
70
+ setText("");
71
+ setError(null);
72
+ setMetadata(null);
73
+ setIsStreaming(false);
74
+ }, [stop]);
75
+ useEffect(() => {
76
+ return () => {
77
+ cancelTextFlush();
78
+ controllerRef.current?.abort();
79
+ controllerRef.current = null;
80
+ };
81
+ }, [cancelTextFlush]);
82
+ return {
83
+ text,
84
+ isStreaming,
85
+ error,
86
+ metadata,
87
+ generate: useCallback((completionOptions) => {
88
+ stop();
89
+ const controller = new AbortController();
90
+ controllerRef.current = controller;
91
+ pendingTextRef.current = "";
92
+ setText("");
93
+ setError(null);
94
+ setMetadata(null);
95
+ setIsStreaming(true);
96
+ const { textStream, metadata: metaPromise } = sdk.ai.streamWithMetadata({
97
+ ...completionOptions,
98
+ signal: controller.signal
99
+ });
100
+ (async () => {
101
+ try {
102
+ let accumulated = "";
103
+ for await (const chunk of textStream) {
104
+ if (controller.signal.aborted) break;
105
+ accumulated += chunk;
106
+ pendingTextRef.current = accumulated;
107
+ scheduleTextFlush();
108
+ optionsRef.current?.onChunk?.(chunk);
109
+ }
110
+ const meta = await metaPromise;
111
+ if (!controller.signal.aborted) {
112
+ commitText();
113
+ setMetadata(meta);
114
+ optionsRef.current?.onFinish?.(accumulated, meta);
115
+ }
116
+ } catch (err) {
117
+ if (!controller.signal.aborted) {
118
+ commitText();
119
+ const e = err instanceof Error ? err : new Error(String(err));
120
+ setError(e);
121
+ optionsRef.current?.onError?.(e);
122
+ }
123
+ } finally {
124
+ if (controllerRef.current === controller) {
125
+ setIsStreaming(false);
126
+ controllerRef.current = null;
127
+ }
128
+ }
129
+ })();
130
+ }, [
131
+ sdk,
132
+ stop,
133
+ scheduleTextFlush,
134
+ commitText
135
+ ]),
136
+ stop,
137
+ reset
138
+ };
139
+ }
140
+
141
+ //#endregion
142
+ //#region src/react/hooks.ts
143
+ const keys = {
144
+ all: ["reopt"],
145
+ entities: (brandappId) => [
146
+ ...keys.all,
147
+ "entities",
148
+ brandappId
149
+ ],
150
+ entity: (entityId) => [
151
+ ...keys.all,
152
+ "entity",
153
+ entityId
154
+ ],
155
+ records: (entityId, query) => [
156
+ ...keys.all,
157
+ "records",
158
+ entityId,
159
+ query
160
+ ],
161
+ recordsInfinite: (entityId, query) => [
162
+ ...keys.all,
163
+ "recordsInfinite",
164
+ entityId,
165
+ query
166
+ ],
167
+ record: (entityId, recordId) => [
168
+ ...keys.all,
169
+ "record",
170
+ entityId,
171
+ recordId
172
+ ],
173
+ recordCount: (entityId, query) => [
174
+ ...keys.all,
175
+ "recordCount",
176
+ entityId,
177
+ query
178
+ ],
179
+ recordsPrefix: (entityId) => [
180
+ ...keys.all,
181
+ "records",
182
+ entityId
183
+ ],
184
+ recordsInfinitePrefix: (entityId) => [
185
+ ...keys.all,
186
+ "recordsInfinite",
187
+ entityId
188
+ ],
189
+ recordCountPrefix: (entityId) => [
190
+ ...keys.all,
191
+ "recordCount",
192
+ entityId
193
+ ],
194
+ aiCredits: (brandappId) => [
195
+ ...keys.all,
196
+ "ai",
197
+ "credits",
198
+ brandappId
199
+ ],
200
+ aiModels: (brandappId) => [
201
+ ...keys.all,
202
+ "ai",
203
+ "models",
204
+ brandappId
205
+ ],
206
+ aiAgents: (brandappId) => [
207
+ ...keys.all,
208
+ "ai",
209
+ "agents",
210
+ brandappId
211
+ ],
212
+ posts: (brandappId, query) => [
213
+ ...keys.all,
214
+ "posts",
215
+ brandappId,
216
+ query
217
+ ],
218
+ post: (postId) => [
219
+ ...keys.all,
220
+ "post",
221
+ postId
222
+ ],
223
+ postGroups: (brandappId, query) => [
224
+ ...keys.all,
225
+ "postGroups",
226
+ brandappId,
227
+ query
228
+ ],
229
+ postGroup: (groupId) => [
230
+ ...keys.all,
231
+ "postGroup",
232
+ groupId
233
+ ],
234
+ tags: (brandappId, query) => [
235
+ ...keys.all,
236
+ "tags",
237
+ brandappId,
238
+ query
239
+ ],
240
+ files: (brandappId, query) => [
241
+ ...keys.all,
242
+ "files",
243
+ brandappId,
244
+ query
245
+ ],
246
+ filesPrefix: (brandappId) => [
247
+ ...keys.all,
248
+ "files",
249
+ brandappId
250
+ ],
251
+ file: (fileId) => [
252
+ ...keys.all,
253
+ "file",
254
+ fileId
255
+ ],
256
+ folders: (brandappId, query) => [
257
+ ...keys.all,
258
+ "folders",
259
+ brandappId,
260
+ query
261
+ ],
262
+ foldersPrefix: (brandappId) => [
263
+ ...keys.all,
264
+ "folders",
265
+ brandappId
266
+ ],
267
+ fileUsage: (brandappId) => [
268
+ ...keys.all,
269
+ "fileUsage",
270
+ brandappId
271
+ ]
136
272
  };
273
+ /**
274
+ * List every EAV entity defined for the current brandapp, including their
275
+ * attribute metadata. Cached for 5 minutes since the schema rarely changes
276
+ * within a session.
277
+ *
278
+ * @example
279
+ * ```tsx
280
+ * function EntityPicker() {
281
+ * const sdk = useContext(SdkContext);
282
+ * const { data: entities, isPending } = useEavEntities(sdk);
283
+ * if (isPending) return <Spinner />;
284
+ * return (
285
+ * <select>
286
+ * {entities?.map((e) => <option key={e.id}>{e.name}</option>)}
287
+ * </select>
288
+ * );
289
+ * }
290
+ * ```
291
+ */
137
292
  function useEavEntities(sdk, options) {
138
- return useQuery({
139
- queryKey: keys.entities(sdk.config.brandappId),
140
- queryFn: () => sdk.eav.entities.list(),
141
- staleTime: 5 * 60 * 1e3,
142
- // 5 min — schema rarely changes
143
- ...options
144
- });
293
+ return useQuery({
294
+ queryKey: keys.entities(sdk.config.brandappId),
295
+ queryFn: () => sdk.eav.entities.list(),
296
+ staleTime: 300 * 1e3,
297
+ ...options
298
+ });
145
299
  }
146
300
  function useEavEntity(sdk, entityId, options) {
147
- return useQuery({
148
- queryKey: keys.entity(entityId),
149
- queryFn: () => sdk.eav.entities.get(entityId),
150
- staleTime: 5 * 60 * 1e3,
151
- enabled: !!entityId,
152
- ...options
153
- });
301
+ return useQuery({
302
+ queryKey: keys.entity(entityId),
303
+ queryFn: () => sdk.eav.entities.get(entityId),
304
+ staleTime: 300 * 1e3,
305
+ enabled: !!entityId,
306
+ ...options
307
+ });
154
308
  }
309
+ /**
310
+ * List records for an entity with optional filters and pagination.
311
+ *
312
+ * The `query` object is part of the cache key, so changing filters will
313
+ * fetch a fresh page rather than reuse a stale one. For cursor-style
314
+ * pagination prefer `useEavRecordsInfinite`.
315
+ *
316
+ * @example
317
+ * ```tsx
318
+ * import { where } from "@reopt-ai/brandapp-sdk/eav";
319
+ *
320
+ * function ActiveContacts({ entityId }: { entityId: string }) {
321
+ * const sdk = useContext(SdkContext);
322
+ * const { data, isPending } = useEavRecords(sdk, entityId, {
323
+ * filters: [where("status").eq("active")],
324
+ * limit: 50,
325
+ * });
326
+ * if (isPending) return <Spinner />;
327
+ * return <RecordTable records={data?.records ?? []} total={data?.total} />;
328
+ * }
329
+ * ```
330
+ */
155
331
  function useEavRecords(sdk, entityId, query, options) {
156
- return useQuery({
157
- queryKey: keys.records(entityId, query),
158
- queryFn: () => sdk.eav.records.list(entityId, query),
159
- enabled: !!entityId,
160
- ...options
161
- });
332
+ return useQuery({
333
+ queryKey: keys.records(entityId, query),
334
+ queryFn: () => sdk.eav.records.list(entityId, query),
335
+ enabled: !!entityId,
336
+ ...options
337
+ });
162
338
  }
163
339
  function useEavRecordsInfinite(sdk, entityId, query, options) {
164
- return useInfiniteQuery({
165
- queryKey: keys.recordsInfinite(entityId, query),
166
- queryFn: ({ pageParam }) => sdk.eav.records.list(entityId, { ...query, page: pageParam }),
167
- initialPageParam: 1,
168
- getNextPageParam: (lastPage) => lastPage.page < lastPage.totalPages ? lastPage.page + 1 : void 0,
169
- enabled: !!entityId,
170
- ...options
171
- });
340
+ return useInfiniteQuery({
341
+ queryKey: keys.recordsInfinite(entityId, query),
342
+ queryFn: ({ pageParam }) => sdk.eav.records.list(entityId, {
343
+ ...query,
344
+ page: pageParam
345
+ }),
346
+ initialPageParam: 1,
347
+ getNextPageParam: (lastPage) => lastPage.page < lastPage.totalPages ? lastPage.page + 1 : void 0,
348
+ enabled: !!entityId,
349
+ ...options
350
+ });
172
351
  }
173
352
  function useEavRecord(sdk, entityId, recordId, options) {
174
- return useQuery({
175
- queryKey: keys.record(entityId, recordId),
176
- queryFn: () => sdk.eav.records.get(entityId, recordId),
177
- enabled: !!entityId && !!recordId,
178
- ...options
179
- });
353
+ return useQuery({
354
+ queryKey: keys.record(entityId, recordId),
355
+ queryFn: () => sdk.eav.records.get(entityId, recordId),
356
+ enabled: !!entityId && !!recordId,
357
+ ...options
358
+ });
180
359
  }
181
360
  function useEavRecordCount(sdk, entityId, query, options) {
182
- return useQuery({
183
- queryKey: keys.recordCount(entityId, query),
184
- queryFn: () => sdk.eav.records.count(entityId, query),
185
- enabled: !!entityId,
186
- ...options
187
- });
361
+ return useQuery({
362
+ queryKey: keys.recordCount(entityId, query),
363
+ queryFn: () => sdk.eav.records.count(entityId, query),
364
+ enabled: !!entityId,
365
+ ...options
366
+ });
188
367
  }
368
+ /**
369
+ * Create a single record. Automatically invalidates the records list and
370
+ * count caches for this entity on success.
371
+ *
372
+ * @example
373
+ * ```tsx
374
+ * function NewContactForm({ entityId }: { entityId: string }) {
375
+ * const sdk = useContext(SdkContext);
376
+ * const create = useCreateRecord(sdk, entityId);
377
+ *
378
+ * return (
379
+ * <form
380
+ * onSubmit={async (e) => {
381
+ * e.preventDefault();
382
+ * const data = new FormData(e.currentTarget);
383
+ * await create.mutateAsync({
384
+ * values: {
385
+ * name: data.get("name") as string,
386
+ * email: data.get("email") as string,
387
+ * },
388
+ * });
389
+ * }}
390
+ * >
391
+ * <input name="name" />
392
+ * <input name="email" type="email" />
393
+ * <button disabled={create.isPending}>Save</button>
394
+ * {create.error ? <ErrorBanner error={create.error} /> : null}
395
+ * </form>
396
+ * );
397
+ * }
398
+ * ```
399
+ */
189
400
  function useCreateRecord(sdk, entityId, options) {
190
- const queryClient = useQueryClient();
191
- return useMutation({
192
- mutationFn: (input) => sdk.eav.records.create(entityId, input),
193
- onSuccess: () => {
194
- queryClient.invalidateQueries({ queryKey: keys.recordsPrefix(entityId) });
195
- queryClient.invalidateQueries({
196
- queryKey: keys.recordsInfinitePrefix(entityId)
197
- });
198
- queryClient.invalidateQueries({
199
- queryKey: keys.recordCountPrefix(entityId)
200
- });
201
- },
202
- ...options
203
- });
401
+ const queryClient = useQueryClient();
402
+ return useMutation({
403
+ mutationFn: (input) => sdk.eav.records.create(entityId, input),
404
+ onSuccess: () => {
405
+ queryClient.invalidateQueries({ queryKey: keys.recordsPrefix(entityId) });
406
+ queryClient.invalidateQueries({ queryKey: keys.recordsInfinitePrefix(entityId) });
407
+ queryClient.invalidateQueries({ queryKey: keys.recordCountPrefix(entityId) });
408
+ },
409
+ ...options
410
+ });
204
411
  }
205
412
  function useUpdateRecord(sdk, entityId, options) {
206
- const queryClient = useQueryClient();
207
- return useMutation({
208
- mutationFn: ({
209
- recordId,
210
- input
211
- }) => sdk.eav.records.update(entityId, recordId, input),
212
- onSuccess: (_, variables) => {
213
- queryClient.invalidateQueries({ queryKey: keys.recordsPrefix(entityId) });
214
- queryClient.invalidateQueries({
215
- queryKey: keys.recordsInfinitePrefix(entityId)
216
- });
217
- queryClient.invalidateQueries({
218
- queryKey: keys.record(entityId, variables.recordId)
219
- });
220
- },
221
- ...options
222
- });
413
+ const queryClient = useQueryClient();
414
+ return useMutation({
415
+ mutationFn: ({ recordId, input }) => sdk.eav.records.update(entityId, recordId, input),
416
+ onSuccess: (_, variables) => {
417
+ queryClient.invalidateQueries({ queryKey: keys.recordsPrefix(entityId) });
418
+ queryClient.invalidateQueries({ queryKey: keys.recordsInfinitePrefix(entityId) });
419
+ queryClient.invalidateQueries({ queryKey: keys.record(entityId, variables.recordId) });
420
+ },
421
+ ...options
422
+ });
223
423
  }
424
+ /**
425
+ * Delete a record by id. Pass the recordId directly to `mutateAsync`.
426
+ *
427
+ * @example
428
+ * ```tsx
429
+ * const remove = useDeleteRecord(sdk, entityId);
430
+ * <button onClick={() => remove.mutate(record.id)}>Delete</button>
431
+ * ```
432
+ */
224
433
  function useDeleteRecord(sdk, entityId, options) {
225
- const queryClient = useQueryClient();
226
- return useMutation({
227
- mutationFn: (recordId) => sdk.eav.records.delete(entityId, recordId),
228
- onSuccess: () => {
229
- queryClient.invalidateQueries({ queryKey: keys.recordsPrefix(entityId) });
230
- queryClient.invalidateQueries({
231
- queryKey: keys.recordsInfinitePrefix(entityId)
232
- });
233
- queryClient.invalidateQueries({
234
- queryKey: keys.recordCountPrefix(entityId)
235
- });
236
- },
237
- ...options
238
- });
434
+ const queryClient = useQueryClient();
435
+ return useMutation({
436
+ mutationFn: (recordId) => sdk.eav.records.delete(entityId, recordId),
437
+ onSuccess: () => {
438
+ queryClient.invalidateQueries({ queryKey: keys.recordsPrefix(entityId) });
439
+ queryClient.invalidateQueries({ queryKey: keys.recordsInfinitePrefix(entityId) });
440
+ queryClient.invalidateQueries({ queryKey: keys.recordCountPrefix(entityId) });
441
+ },
442
+ ...options
443
+ });
239
444
  }
445
+ /**
446
+ * 레코드 upsert mutation. 필터에 매칭되는 레코드가 있으면 업데이트, 없으면 생성.
447
+ *
448
+ * @example
449
+ * ```tsx
450
+ * const upsert = useUpsertRecord(sdk, entityId);
451
+ * await upsert.mutateAsync({
452
+ * filters: [{ attributeId: attrs.key, operator: "eq", value: "theme" }],
453
+ * values: { [attrs.key]: "theme", [attrs.value]: "dark" },
454
+ * });
455
+ * ```
456
+ */
240
457
  function useUpsertRecord(sdk, entityId, options) {
241
- const queryClient = useQueryClient();
242
- return useMutation({
243
- mutationFn: (input) => sdk.eav.records.upsert(entityId, input),
244
- onSuccess: () => {
245
- queryClient.invalidateQueries({ queryKey: keys.recordsPrefix(entityId) });
246
- queryClient.invalidateQueries({
247
- queryKey: keys.recordsInfinitePrefix(entityId)
248
- });
249
- queryClient.invalidateQueries({
250
- queryKey: keys.recordCountPrefix(entityId)
251
- });
252
- },
253
- ...options
254
- });
458
+ const queryClient = useQueryClient();
459
+ return useMutation({
460
+ mutationFn: (input) => sdk.eav.records.upsert(entityId, input),
461
+ onSuccess: () => {
462
+ queryClient.invalidateQueries({ queryKey: keys.recordsPrefix(entityId) });
463
+ queryClient.invalidateQueries({ queryKey: keys.recordsInfinitePrefix(entityId) });
464
+ queryClient.invalidateQueries({ queryKey: keys.recordCountPrefix(entityId) });
465
+ },
466
+ ...options
467
+ });
255
468
  }
469
+ /**
470
+ * 최대 100개 레코드를 한 번에 생성하는 mutation.
471
+ *
472
+ * @example
473
+ * ```tsx
474
+ * const bulkCreate = useBulkCreateRecords(sdk, entityId);
475
+ * await bulkCreate.mutateAsync([
476
+ * { values: { name: "Alice" } },
477
+ * { values: { name: "Bob" } },
478
+ * ]);
479
+ * ```
480
+ */
256
481
  function useBulkCreateRecords(sdk, entityId, options) {
257
- const queryClient = useQueryClient();
258
- return useMutation({
259
- mutationFn: (records) => sdk.eav.records.bulkCreate(entityId, records),
260
- onSuccess: () => {
261
- queryClient.invalidateQueries({ queryKey: keys.recordsPrefix(entityId) });
262
- queryClient.invalidateQueries({
263
- queryKey: keys.recordsInfinitePrefix(entityId)
264
- });
265
- queryClient.invalidateQueries({
266
- queryKey: keys.recordCountPrefix(entityId)
267
- });
268
- },
269
- ...options
270
- });
482
+ const queryClient = useQueryClient();
483
+ return useMutation({
484
+ mutationFn: (records) => sdk.eav.records.bulkCreate(entityId, records),
485
+ onSuccess: () => {
486
+ queryClient.invalidateQueries({ queryKey: keys.recordsPrefix(entityId) });
487
+ queryClient.invalidateQueries({ queryKey: keys.recordsInfinitePrefix(entityId) });
488
+ queryClient.invalidateQueries({ queryKey: keys.recordCountPrefix(entityId) });
489
+ },
490
+ ...options
491
+ });
271
492
  }
493
+ /**
494
+ * 최대 100개 레코드를 한 번에 업데이트하는 mutation.
495
+ */
272
496
  function useBulkUpdateRecords(sdk, entityId, options) {
273
- const queryClient = useQueryClient();
274
- return useMutation({
275
- mutationFn: (updates) => sdk.eav.records.bulkUpdate(entityId, updates),
276
- onSuccess: (_data, variables) => {
277
- queryClient.invalidateQueries({ queryKey: keys.recordsPrefix(entityId) });
278
- queryClient.invalidateQueries({
279
- queryKey: keys.recordsInfinitePrefix(entityId)
280
- });
281
- for (const { id } of variables) {
282
- queryClient.invalidateQueries({
283
- queryKey: keys.record(entityId, id)
284
- });
285
- }
286
- },
287
- ...options
288
- });
497
+ const queryClient = useQueryClient();
498
+ return useMutation({
499
+ mutationFn: (updates) => sdk.eav.records.bulkUpdate(entityId, updates),
500
+ onSuccess: (_data, variables) => {
501
+ queryClient.invalidateQueries({ queryKey: keys.recordsPrefix(entityId) });
502
+ queryClient.invalidateQueries({ queryKey: keys.recordsInfinitePrefix(entityId) });
503
+ for (const { id } of variables) queryClient.invalidateQueries({ queryKey: keys.record(entityId, id) });
504
+ },
505
+ ...options
506
+ });
289
507
  }
508
+ /**
509
+ * 최대 100개 레코드를 한 번에 삭제하는 mutation. 삭제된 레코드 수를 반환.
510
+ */
290
511
  function useBulkDeleteRecords(sdk, entityId, options) {
291
- const queryClient = useQueryClient();
292
- return useMutation({
293
- mutationFn: (ids) => sdk.eav.records.bulkDelete(entityId, ids),
294
- onSuccess: () => {
295
- queryClient.invalidateQueries({ queryKey: keys.recordsPrefix(entityId) });
296
- queryClient.invalidateQueries({
297
- queryKey: keys.recordsInfinitePrefix(entityId)
298
- });
299
- queryClient.invalidateQueries({
300
- queryKey: keys.recordCountPrefix(entityId)
301
- });
302
- },
303
- ...options
304
- });
512
+ const queryClient = useQueryClient();
513
+ return useMutation({
514
+ mutationFn: (ids) => sdk.eav.records.bulkDelete(entityId, ids),
515
+ onSuccess: () => {
516
+ queryClient.invalidateQueries({ queryKey: keys.recordsPrefix(entityId) });
517
+ queryClient.invalidateQueries({ queryKey: keys.recordsInfinitePrefix(entityId) });
518
+ queryClient.invalidateQueries({ queryKey: keys.recordCountPrefix(entityId) });
519
+ },
520
+ ...options
521
+ });
305
522
  }
523
+ /**
524
+ * 필터에 매칭되는 모든 레코드를 삭제하는 mutation. 삭제된 수를 반환.
525
+ */
306
526
  function useDeleteRecordsWhere(sdk, entityId, options) {
307
- const queryClient = useQueryClient();
308
- return useMutation({
309
- mutationFn: (input) => sdk.eav.records.deleteWhere(entityId, input),
310
- onSuccess: () => {
311
- queryClient.invalidateQueries({ queryKey: keys.recordsPrefix(entityId) });
312
- queryClient.invalidateQueries({
313
- queryKey: keys.recordsInfinitePrefix(entityId)
314
- });
315
- queryClient.invalidateQueries({
316
- queryKey: keys.recordCountPrefix(entityId)
317
- });
318
- },
319
- ...options
320
- });
527
+ const queryClient = useQueryClient();
528
+ return useMutation({
529
+ mutationFn: (input) => sdk.eav.records.deleteWhere(entityId, input),
530
+ onSuccess: () => {
531
+ queryClient.invalidateQueries({ queryKey: keys.recordsPrefix(entityId) });
532
+ queryClient.invalidateQueries({ queryKey: keys.recordsInfinitePrefix(entityId) });
533
+ queryClient.invalidateQueries({ queryKey: keys.recordCountPrefix(entityId) });
534
+ },
535
+ ...options
536
+ });
321
537
  }
538
+ /**
539
+ * BrandApp AI 크레딧 잔액 조회
540
+ *
541
+ * @example
542
+ * ```tsx
543
+ * const { data: credits } = useAiCredits(sdk);
544
+ * // credits?.balance, credits?.limit, credits?.status
545
+ * ```
546
+ */
322
547
  function useAiCredits(sdk, options) {
323
- return useQuery({
324
- queryKey: keys.aiCredits(sdk.config.brandappId),
325
- queryFn: () => sdk.ai.credits(),
326
- staleTime: 30 * 1e3,
327
- // 30초 — 크레딧은 자주 변동
328
- ...options
329
- });
548
+ return useQuery({
549
+ queryKey: keys.aiCredits(sdk.config.brandappId),
550
+ queryFn: () => sdk.ai.credits(),
551
+ staleTime: 30 * 1e3,
552
+ ...options
553
+ });
330
554
  }
555
+ /**
556
+ * BrandApp AI 사용 가능 모델 목록
557
+ *
558
+ * @example
559
+ * ```tsx
560
+ * const { data: models } = useAiModels(sdk);
561
+ * // models?.map(m => m.id)
562
+ * ```
563
+ */
331
564
  function useAiModels(sdk, options) {
332
- return useQuery({
333
- queryKey: keys.aiModels(sdk.config.brandappId),
334
- queryFn: () => sdk.ai.models(),
335
- staleTime: 5 * 60 * 1e3,
336
- // 5분 — 모델 목록은 자주 안 바뀜
337
- ...options
338
- });
565
+ return useQuery({
566
+ queryKey: keys.aiModels(sdk.config.brandappId),
567
+ queryFn: () => sdk.ai.models(),
568
+ staleTime: 300 * 1e3,
569
+ ...options
570
+ });
339
571
  }
572
+ /**
573
+ * BrandApp에서 사용 가능한 커스텀 에이전트 목록
574
+ *
575
+ * @example
576
+ * ```tsx
577
+ * const { data: agents } = useAiAgents(sdk);
578
+ * // agents?.map(a => ({ id: a.id, name: a.name, defaultModel: a.defaultModel }))
579
+ * ```
580
+ */
340
581
  function useAiAgents(sdk, options) {
341
- return useQuery({
342
- queryKey: keys.aiAgents(sdk.config.brandappId),
343
- queryFn: () => sdk.ai.agents(),
344
- staleTime: 5 * 60 * 1e3,
345
- // 5분 — 에이전트 목록은 자주 안 바뀜
346
- ...options
347
- });
582
+ return useQuery({
583
+ queryKey: keys.aiAgents(sdk.config.brandappId),
584
+ queryFn: () => sdk.ai.agents(),
585
+ staleTime: 300 * 1e3,
586
+ ...options
587
+ });
348
588
  }
589
+ /**
590
+ * AI 텍스트 생성 (non-streaming) mutation
591
+ *
592
+ * @example
593
+ * ```tsx
594
+ * const completion = useAiCompletion(sdk);
595
+ *
596
+ * const handleSubmit = () => {
597
+ * completion.mutate({
598
+ * messages: [{ role: "user", content: "안녕하세요" }],
599
+ * model: "anthropic/claude-haiku-4.5",
600
+ * });
601
+ * };
602
+ * // completion.data?.message.content
603
+ * ```
604
+ */
349
605
  function useAiCompletion(sdk, options) {
350
- const queryClient = useQueryClient();
351
- return useMutation({
352
- mutationFn: (input) => sdk.ai.complete(input),
353
- ...options,
354
- // 크레딧이 차감됐으므로 잔액 쿼리를 무효화(배지 즉시 갱신). caller onSuccess 병합.
355
- onSuccess: (...args) => {
356
- queryClient.invalidateQueries({
357
- queryKey: keys.aiCredits(sdk.config.brandappId)
358
- });
359
- return options?.onSuccess?.(...args);
360
- }
361
- });
606
+ const queryClient = useQueryClient();
607
+ return useMutation({
608
+ mutationFn: (input) => sdk.ai.complete(input),
609
+ ...options,
610
+ onSuccess: (...args) => {
611
+ queryClient.invalidateQueries({ queryKey: keys.aiCredits(sdk.config.brandappId) });
612
+ return options?.onSuccess?.(...args);
613
+ }
614
+ });
362
615
  }
616
+ /**
617
+ * AI 이미지 생성 mutation
618
+ *
619
+ * @example
620
+ * ```tsx
621
+ * const imageGen = useAiImageGenerate(sdk);
622
+ *
623
+ * const handleGenerate = () => {
624
+ * imageGen.mutate({
625
+ * prompt: "브랜드 배너 이미지",
626
+ * style: "minimalist",
627
+ * aspectRatio: "16:9",
628
+ * });
629
+ * };
630
+ * // imageGen.data?.url
631
+ * ```
632
+ */
363
633
  function useAiImageGenerate(sdk, options) {
364
- const queryClient = useQueryClient();
365
- return useMutation({
366
- mutationFn: (input) => sdk.ai.generateImage(input),
367
- ...options,
368
- onSuccess: (...args) => {
369
- queryClient.invalidateQueries({
370
- queryKey: keys.aiCredits(sdk.config.brandappId)
371
- });
372
- return options?.onSuccess?.(...args);
373
- }
374
- });
634
+ const queryClient = useQueryClient();
635
+ return useMutation({
636
+ mutationFn: (input) => sdk.ai.generateImage(input),
637
+ ...options,
638
+ onSuccess: (...args) => {
639
+ queryClient.invalidateQueries({ queryKey: keys.aiCredits(sdk.config.brandappId) });
640
+ return options?.onSuccess?.(...args);
641
+ }
642
+ });
375
643
  }
644
+ /**
645
+ * Post 목록 조회
646
+ *
647
+ * @example
648
+ * ```tsx
649
+ * const { data } = usePostList(sdk, { status: "published", limit: 10 });
650
+ * // data?.records (Post[]), data?.total
651
+ * ```
652
+ */
376
653
  function usePostList(sdk, query, options) {
377
- return useQuery({
378
- queryKey: keys.posts(sdk.config.brandappId, query),
379
- queryFn: () => sdk.cms.posts.list(query),
380
- ...options
381
- });
654
+ return useQuery({
655
+ queryKey: keys.posts(sdk.config.brandappId, query),
656
+ queryFn: () => sdk.cms.posts.list(query),
657
+ ...options
658
+ });
382
659
  }
660
+ /**
661
+ * 단일 Post 조회 (with document content)
662
+ *
663
+ * @example
664
+ * ```tsx
665
+ * const { data: post } = usePost(sdk, postId);
666
+ * // post?.title, post?.document.contentRich
667
+ * ```
668
+ */
383
669
  function usePost(sdk, postId, options) {
384
- return useQuery({
385
- queryKey: keys.post(postId),
386
- queryFn: () => sdk.cms.posts.get(postId),
387
- enabled: !!postId,
388
- ...options
389
- });
670
+ return useQuery({
671
+ queryKey: keys.post(postId),
672
+ queryFn: () => sdk.cms.posts.get(postId),
673
+ enabled: !!postId,
674
+ ...options
675
+ });
390
676
  }
677
+ /**
678
+ * PostGroup 목록 조회
679
+ *
680
+ * @example
681
+ * ```tsx
682
+ * const { data } = usePostGroupList(sdk, { sortBy: "name" });
683
+ * // data?.records (PostGroup[]), data?.total
684
+ * ```
685
+ */
391
686
  function usePostGroupList(sdk, query, options) {
392
- return useQuery({
393
- queryKey: keys.postGroups(sdk.config.brandappId, query),
394
- queryFn: () => sdk.cms.postGroups.list(query),
395
- ...options
396
- });
687
+ return useQuery({
688
+ queryKey: keys.postGroups(sdk.config.brandappId, query),
689
+ queryFn: () => sdk.cms.postGroups.list(query),
690
+ ...options
691
+ });
397
692
  }
693
+ /**
694
+ * 단일 PostGroup 조회
695
+ *
696
+ * @example
697
+ * ```tsx
698
+ * const { data: group } = usePostGroup(sdk, groupId);
699
+ * // group?.name, group?.postCount
700
+ * ```
701
+ */
398
702
  function usePostGroup(sdk, groupId, options) {
399
- return useQuery({
400
- queryKey: keys.postGroup(groupId),
401
- queryFn: () => sdk.cms.postGroups.get(groupId),
402
- enabled: !!groupId,
403
- ...options
404
- });
703
+ return useQuery({
704
+ queryKey: keys.postGroup(groupId),
705
+ queryFn: () => sdk.cms.postGroups.get(groupId),
706
+ enabled: !!groupId,
707
+ ...options
708
+ });
405
709
  }
710
+ /**
711
+ * Slug 기반 단일 Post 조회. 외부 사이트의 `/blog/[slug]` 같은 라우트에서
712
+ * id 매핑 없이 사용. (서버 컴포넌트에서는 `sdk.cms.posts.getBySlug`를
713
+ * 직접 호출하는 편이 추가 hop을 피할 수 있다.)
714
+ *
715
+ * @example
716
+ * ```tsx
717
+ * const { data: post } = usePostBySlug(sdk, slug);
718
+ * ```
719
+ */
406
720
  function usePostBySlug(sdk, slug, opts, options) {
407
- return useQuery({
408
- queryKey: [
409
- ...keys.all,
410
- "postBySlug",
411
- sdk.config.brandappId,
412
- slug,
413
- opts
414
- ],
415
- queryFn: () => sdk.cms.posts.getBySlug(slug, opts),
416
- enabled: !!slug,
417
- ...options
418
- });
721
+ return useQuery({
722
+ queryKey: [
723
+ ...keys.all,
724
+ "postBySlug",
725
+ sdk.config.brandappId,
726
+ slug,
727
+ opts
728
+ ],
729
+ queryFn: () => sdk.cms.posts.getBySlug(slug, opts),
730
+ enabled: !!slug,
731
+ ...options
732
+ });
419
733
  }
734
+ /**
735
+ * Brand 범위에서 사용된 포스트 태그 목록.
736
+ *
737
+ * @example
738
+ * ```tsx
739
+ * const { data: tags } = useCmsTags(sdk, { groupId: blogId });
740
+ * // tags?.[0]: { id, text, postCount }
741
+ * ```
742
+ */
420
743
  function useCmsTags(sdk, query, options) {
421
- return useQuery({
422
- queryKey: keys.tags(sdk.config.brandappId, query),
423
- queryFn: () => sdk.cms.tags.list(query),
424
- ...options
425
- });
744
+ return useQuery({
745
+ queryKey: keys.tags(sdk.config.brandappId, query),
746
+ queryFn: () => sdk.cms.tags.list(query),
747
+ ...options
748
+ });
426
749
  }
750
+ /**
751
+ * 파일 목록 조회
752
+ *
753
+ * @example
754
+ * ```tsx
755
+ * const { data } = useFiles(sdk, { contentType: "image/*", sortBy: "createdAt" });
756
+ * // data?.data (FileInfo[]), data?.meta
757
+ * ```
758
+ */
427
759
  function useFiles(sdk, query, options) {
428
- return useQuery({
429
- queryKey: keys.files(sdk.config.brandappId, query),
430
- queryFn: () => sdk.files.list(query),
431
- ...options
432
- });
760
+ return useQuery({
761
+ queryKey: keys.files(sdk.config.brandappId, query),
762
+ queryFn: () => sdk.files.list(query),
763
+ ...options
764
+ });
433
765
  }
766
+ /**
767
+ * 단일 파일 조회
768
+ *
769
+ * @example
770
+ * ```tsx
771
+ * const { data: file } = useFile(sdk, fileId);
772
+ * // file?.name, file?.url
773
+ * ```
774
+ */
434
775
  function useFile(sdk, fileId, options) {
435
- return useQuery({
436
- queryKey: keys.file(fileId),
437
- queryFn: () => sdk.files.get(fileId),
438
- enabled: !!fileId,
439
- ...options
440
- });
776
+ return useQuery({
777
+ queryKey: keys.file(fileId),
778
+ queryFn: () => sdk.files.get(fileId),
779
+ enabled: !!fileId,
780
+ ...options
781
+ });
441
782
  }
783
+ /**
784
+ * 파일 삭제 mutation
785
+ *
786
+ * @example
787
+ * ```tsx
788
+ * const deleteFile = useDeleteFile(sdk);
789
+ * await deleteFile.mutateAsync("file-uuid");
790
+ * ```
791
+ */
442
792
  function useDeleteFile(sdk, options) {
443
- const queryClient = useQueryClient();
444
- return useMutation({
445
- mutationFn: (fileId) => sdk.files.delete(fileId),
446
- onSuccess: () => {
447
- queryClient.invalidateQueries({
448
- queryKey: keys.files(sdk.config.brandappId)
449
- });
450
- },
451
- ...options
452
- });
793
+ const queryClient = useQueryClient();
794
+ return useMutation({
795
+ mutationFn: (fileId) => sdk.files.delete(fileId),
796
+ onSuccess: () => {
797
+ queryClient.invalidateQueries({ queryKey: keys.filesPrefix(sdk.config.brandappId) });
798
+ queryClient.invalidateQueries({ queryKey: keys.foldersPrefix(sdk.config.brandappId) });
799
+ queryClient.invalidateQueries({ queryKey: keys.fileUsage(sdk.config.brandappId) });
800
+ },
801
+ ...options
802
+ });
453
803
  }
804
+ /**
805
+ * 파일 업로드 mutation
806
+ *
807
+ * @example
808
+ * ```tsx
809
+ * const upload = useUploadFile(sdk);
810
+ * const file = await upload.mutateAsync({
811
+ * file: blob,
812
+ * options: { name: "banner.png" },
813
+ * });
814
+ * console.log(file.url);
815
+ * ```
816
+ */
454
817
  function useUploadFile(sdk, options) {
455
- const queryClient = useQueryClient();
456
- return useMutation({
457
- mutationFn: (input) => sdk.files.upload(input.file, input.options),
458
- onSuccess: () => {
459
- queryClient.invalidateQueries({
460
- queryKey: keys.files(sdk.config.brandappId)
461
- });
462
- },
463
- ...options
464
- });
818
+ const queryClient = useQueryClient();
819
+ return useMutation({
820
+ mutationFn: (input) => sdk.files.upload(input.file, input.options),
821
+ onSuccess: () => {
822
+ queryClient.invalidateQueries({ queryKey: keys.filesPrefix(sdk.config.brandappId) });
823
+ queryClient.invalidateQueries({ queryKey: keys.foldersPrefix(sdk.config.brandappId) });
824
+ queryClient.invalidateQueries({ queryKey: keys.fileUsage(sdk.config.brandappId) });
825
+ },
826
+ ...options
827
+ });
828
+ }
829
+ /**
830
+ * 파일 수정(rename/move) mutation
831
+ *
832
+ * @example
833
+ * ```tsx
834
+ * const update = useUpdateFile(sdk);
835
+ * await update.mutateAsync({ fileId, input: { name: "renamed.png" } });
836
+ * await update.mutateAsync({ fileId, input: { folderId } }); // 폴더 이동
837
+ * ```
838
+ */
839
+ function useUpdateFile(sdk, options) {
840
+ const queryClient = useQueryClient();
841
+ return useMutation({
842
+ mutationFn: ({ fileId, input }) => sdk.files.update(fileId, input),
843
+ onSuccess: (_data, variables) => {
844
+ queryClient.invalidateQueries({ queryKey: keys.filesPrefix(sdk.config.brandappId) });
845
+ queryClient.invalidateQueries({ queryKey: keys.file(variables.fileId) });
846
+ queryClient.invalidateQueries({ queryKey: keys.foldersPrefix(sdk.config.brandappId) });
847
+ },
848
+ ...options
849
+ });
850
+ }
851
+ /**
852
+ * 직속 자식 폴더 목록 조회 (미지정 = 루트)
853
+ *
854
+ * @example
855
+ * ```tsx
856
+ * const { data: rootFolders } = useFolders(sdk);
857
+ * const { data: children } = useFolders(sdk, { parentId: folder.id });
858
+ * ```
859
+ */
860
+ function useFolders(sdk, query, options) {
861
+ return useQuery({
862
+ queryKey: keys.folders(sdk.config.brandappId, query),
863
+ queryFn: () => sdk.files.listFolders(query),
864
+ ...options
865
+ });
866
+ }
867
+ /**
868
+ * 폴더 생성 mutation
869
+ */
870
+ function useCreateFolder(sdk, options) {
871
+ const queryClient = useQueryClient();
872
+ return useMutation({
873
+ mutationFn: (input) => sdk.files.createFolder(input),
874
+ onSuccess: () => {
875
+ queryClient.invalidateQueries({ queryKey: keys.foldersPrefix(sdk.config.brandappId) });
876
+ },
877
+ ...options
878
+ });
879
+ }
880
+ /**
881
+ * 폴더 수정(rename/move) mutation
882
+ */
883
+ function useUpdateFolder(sdk, options) {
884
+ const queryClient = useQueryClient();
885
+ return useMutation({
886
+ mutationFn: ({ folderId, input }) => sdk.files.updateFolder(folderId, input),
887
+ onSuccess: () => {
888
+ queryClient.invalidateQueries({ queryKey: keys.foldersPrefix(sdk.config.brandappId) });
889
+ },
890
+ ...options
891
+ });
892
+ }
893
+ /**
894
+ * 폴더 삭제 mutation — 비어있어야 성공 (아니면 409 FOLDER_NOT_EMPTY)
895
+ */
896
+ function useDeleteFolder(sdk, options) {
897
+ const queryClient = useQueryClient();
898
+ return useMutation({
899
+ mutationFn: (folderId) => sdk.files.deleteFolder(folderId),
900
+ onSuccess: () => {
901
+ queryClient.invalidateQueries({ queryKey: keys.foldersPrefix(sdk.config.brandappId) });
902
+ },
903
+ ...options
904
+ });
905
+ }
906
+ /**
907
+ * 저장공간 사용량 조회 — 사용량 미터·임박 경고용
908
+ *
909
+ * @example
910
+ * ```tsx
911
+ * const { data: usage } = useFileUsage(sdk);
912
+ * // usage?.usedBytes / usage?.limitBytes (null = 무제한)
913
+ * ```
914
+ */
915
+ function useFileUsage(sdk, options) {
916
+ return useQuery({
917
+ queryKey: keys.fileUsage(sdk.config.brandappId),
918
+ queryFn: () => sdk.files.usage(),
919
+ ...options
920
+ });
465
921
  }
466
922
 
467
- export { keys as reoptQueryKeys, useAiAgents, useAiCompletion, useAiCredits, useAiImageGenerate, useAiModels, useAiStream, useBulkCreateRecords, useBulkDeleteRecords, useBulkUpdateRecords, useCmsTags, useCreateRecord, useDeleteFile, useDeleteRecord, useDeleteRecordsWhere, useEavEntities, useEavEntity, useEavRecord, useEavRecordCount, useEavRecords, useEavRecordsInfinite, useFile, useFiles, usePost, usePostBySlug, usePostGroup, usePostGroupList, usePostList, useUpdateRecord, useUploadFile, useUpsertRecord };
468
- //# sourceMappingURL=hooks.js.map
923
+ //#endregion
924
+ export { keys as reoptQueryKeys, useAiAgents, useAiCompletion, useAiCredits, useAiImageGenerate, useAiModels, useAiStream, useBulkCreateRecords, useBulkDeleteRecords, useBulkUpdateRecords, useCmsTags, useCreateFolder, useCreateRecord, useDeleteFile, useDeleteFolder, useDeleteRecord, useDeleteRecordsWhere, useEavEntities, useEavEntity, useEavRecord, useEavRecordCount, useEavRecords, useEavRecordsInfinite, useFile, useFileUsage, useFiles, useFolders, usePost, usePostBySlug, usePostGroup, usePostGroupList, usePostList, useUpdateFile, useUpdateFolder, useUpdateRecord, useUploadFile, useUpsertRecord };
469
925
  //# sourceMappingURL=hooks.js.map