@simpleapps-com/augur-server 2.1.0 → 2.1.2

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.
@@ -1,349 +0,0 @@
1
- import { AugurAPI } from '@simpleapps-com/augur-api';
2
- import { ListResult, EdgeCacheValue } from '@simpleapps-com/augur-core';
3
- import { TCategory, TCategoryItemsResult, TItemsFilters, TProductItem, TAttribute, TInvMast, TInvMastDoc, TStock, TItemAccessory, TSearchSuggestionsResponse, TShippingMethod, TJoomlaContent, TMenu, MenuItem, TPasswordVerification, TSmartyStreets } from '@simpleapps-com/augur-utils';
4
-
5
- /**
6
- * Standardized paginated response shape.
7
- * Works with any factory method — compose with `paginateOffset()`.
8
- */
9
- interface PaginatedResult<T> {
10
- data: T[];
11
- total: number;
12
- nextCursor?: number;
13
- hasMore: boolean;
14
- }
15
- /**
16
- * Wraps a list of items with offset-based pagination metadata.
17
- *
18
- * Use this to standardize pagination responses from any factory method.
19
- * Compatible with React Query's infinite query pattern (`getNextPageParam`).
20
- *
21
- * @param items - The items returned from the current page
22
- * @param pageParam - The current page number (0-based)
23
- * @param limit - The page size
24
- * @param total - Optional total count of items (from API response)
25
- *
26
- * @example
27
- * ```ts
28
- * const result = await actions.items.getCategoryItems(uid, {
29
- * ...filters, offset: page * 24, limit: 24,
30
- * });
31
- * return paginateOffset(result.items, page, 24, result.total);
32
- * // { data: [...], total: 150, nextCursor: 1, hasMore: true }
33
- * ```
34
- */
35
- declare function paginateOffset<T>(items: T[], pageParam: number, limit: number, total?: number): PaginatedResult<T>;
36
-
37
- /** Derived from augur-api SDK — keeps types in sync automatically. */
38
- type ItemsApiClient = Pick<AugurAPI, "items">;
39
- interface ItemActionsConfig {
40
- /** Cache key prefix (e.g. "ampro:"). Default: "". */
41
- cachePrefix?: string;
42
- /** CDN edge cache value for most calls. Default: 1 (hour). */
43
- edgeCache?: EdgeCacheValue;
44
- /** CDN edge cache for rarely-changing data like FAQs. Default: 8 (hours). */
45
- longEdgeCache?: EdgeCacheValue;
46
- /** Redis TTL for most calls in seconds. Default: 3600 (1 hour). */
47
- redisTtl?: number;
48
- /** Redis TTL for rarely-changing data in seconds. Default: 28800 (8 hours). */
49
- longRedisTtl?: number;
50
- /** Sort category children by sequenceNo. Default: true. */
51
- sortChildren?: boolean;
52
- /** Prefix prepended to sortBy filter values (e.g. "item_category_sequence_no_min|"). */
53
- sortByPrefix?: string;
54
- }
55
- /** Typed options for getItemCategory. */
56
- interface GetItemCategoryOptions {
57
- childrenFilter?: string;
58
- childrenLimit?: number;
59
- childrenOffset?: number;
60
- classId5List?: string;
61
- filters?: Record<string, string>;
62
- orderBy?: string;
63
- path?: string;
64
- productCollection?: string;
65
- rootItemCategoryId?: string;
66
- }
67
- interface ItemActions {
68
- itemCategoryLookup: (path: string) => Promise<unknown>;
69
- getItemCategory: (uid: number, options?: GetItemCategoryOptions) => Promise<TCategory>;
70
- getCategoryItems: {
71
- (uid: number, filters: Record<string, unknown>): Promise<TCategoryItemsResult>;
72
- (uid: number, itemsFilters: TItemsFilters): Promise<TCategoryItemsResult>;
73
- };
74
- getCategoryItemsInfinite: (uid: number, itemsFilters?: TItemsFilters, pageParam?: number) => Promise<PaginatedResult<TProductItem>>;
75
- getItemAttributes: (categoryUid: number) => Promise<{
76
- attributes: TAttribute[];
77
- }>;
78
- getInvMast: (uid: number) => Promise<TInvMast>;
79
- getInvMastDoc: {
80
- (params: {
81
- invMastUid?: number;
82
- itemId?: string;
83
- includePricing?: "Y" | "N";
84
- }): Promise<TInvMastDoc>;
85
- (invMastUid: number, itemId?: string, includePricing?: "Y" | "N"): Promise<TInvMastDoc>;
86
- };
87
- getStock: (invMastUid: number) => Promise<TStock>;
88
- getStockCompanySummary: (invMastUid: number) => Promise<Record<string, number>>;
89
- getItemFaqs: (invMastUid: number) => Promise<ListResult>;
90
- getItemSubstitutes: (invMastUid: number) => Promise<ListResult>;
91
- getItemAccessories: (invMastUid: number) => Promise<ListResult<TItemAccessory>>;
92
- getSimilarItems: (invMastUid: number) => Promise<ListResult>;
93
- batchGetInvMastDocs: (params: {
94
- invMastUid?: number;
95
- itemId?: string;
96
- }[]) => Promise<Record<string, TInvMastDoc>>;
97
- batchGetStockData: (invMastUids: number[]) => Promise<Record<number, TStock>>;
98
- }
99
- /**
100
- * @deprecated Use `createSiteActions()` instead. This factory will be removed in the next major version.
101
- *
102
- * Creates server-side item actions with Redis caching and edge cache support.
103
- *
104
- * Uses `withServerCache` which produces cache keys compatible with augur-hooks'
105
- * `withCache`, so server-prefetched data is shared with client-side hooks.
106
- *
107
- * @example
108
- * ```ts
109
- * // lib/item-actions.ts
110
- * import { createItemActions } from "@simpleapps-com/augur-server";
111
- * import { getAugurClient } from "./augur-client";
112
- *
113
- * export const itemActions = createItemActions(getAugurClient(), {
114
- * cachePrefix: "ampro:",
115
- * });
116
- *
117
- * // In a server component:
118
- * const category = await itemActions.getItemCategory(123);
119
- * const doc = await itemActions.getInvMastDoc({ itemId: "ITEM-1" });
120
- * ```
121
- */
122
- declare function createItemActions(api: ItemsApiClient, config?: ItemActionsConfig): ItemActions;
123
-
124
- /** Derived from augur-api SDK — keeps types in sync automatically. */
125
- type SearchApiClient = Pick<AugurAPI, "opensearch">;
126
- interface SearchActionsConfig {
127
- /** Cache key prefix (e.g. "ampro:"). Default: "". */
128
- cachePrefix?: string;
129
- /** CDN edge cache value passed to SDK. Default: 1 (hour). */
130
- edgeCache?: EdgeCacheValue;
131
- /** Redis TTL for search lookups in seconds. Default: 3600 (1 hour). */
132
- redisTtl?: number;
133
- /** Default source fields for item search. Default: "display_desc". */
134
- defaultSourceFields?: string;
135
- }
136
- /** Paginated response for infinite scroll. */
137
- interface SearchPage {
138
- data: TProductItem[];
139
- total: number;
140
- nextCursor?: number;
141
- }
142
- interface SearchActions {
143
- getSearchAttributes: (q: string) => Promise<{
144
- attributes: TAttribute[];
145
- }>;
146
- getSearchSuggestions: (q: string, limit?: number, offset?: number) => Promise<TSearchSuggestionsResponse>;
147
- itemSearch: (filters: {
148
- q: string;
149
- limit: number;
150
- offset: number;
151
- sortBy?: string;
152
- filters?: [string, string][];
153
- }, itemCategoryUid?: number | string) => Promise<{
154
- items: TProductItem[];
155
- totalResults: number;
156
- }>;
157
- itemSearchInfinite: (filters: {
158
- q: string;
159
- limit: number;
160
- sortBy?: string;
161
- filters?: [string, string][];
162
- }, itemCategoryUid?: number | string, pageParam?: number) => Promise<SearchPage>;
163
- }
164
- /**
165
- * @deprecated Use `createSiteActions()` instead. This factory will be removed in the next major version.
166
- *
167
- * Creates server-side search actions with Redis caching and edge cache support.
168
- *
169
- * Uses `withServerCache` which produces cache keys compatible with augur-hooks'
170
- * `withCache`, so server-prefetched data is shared with client-side hooks.
171
- *
172
- * @example
173
- * ```ts
174
- * // lib/search-actions.ts
175
- * import { createSearchActions } from "@simpleapps-com/augur-server";
176
- * import { getAugurClient } from "./augur-client";
177
- *
178
- * export const searchActions = createSearchActions(getAugurClient(), {
179
- * cachePrefix: "ampro:",
180
- * });
181
- *
182
- * // In a server component:
183
- * const attrs = await searchActions.getSearchAttributes("widget");
184
- * const results = await searchActions.itemSearch({ q: "widget", limit: 20, offset: 0 });
185
- * ```
186
- */
187
- declare function createSearchActions(api: SearchApiClient, config?: SearchActionsConfig): SearchActions;
188
-
189
- interface ShippingAddress {
190
- address1: string;
191
- city: string;
192
- state: string;
193
- postalCode: string;
194
- country?: string;
195
- }
196
- /** Derived from augur-api SDK — keeps types in sync automatically. */
197
- type ShippingApiClient = Pick<AugurAPI, "ups">;
198
- interface ShippingActionsConfig {
199
- /** Warehouse/origin address for rate calculations. */
200
- fromAddress: ShippingAddress;
201
- /** UPS service codes to filter results. Default: undefined (return all). */
202
- defaultServiceCodes?: string[];
203
- /** Cache key prefix (e.g. "ampro:"). Default: "". */
204
- cachePrefix?: string;
205
- /** CDN edge cache value passed to SDK. Default: 1 (hour). */
206
- edgeCache?: EdgeCacheValue;
207
- /** Redis TTL for shipping rate lookups in seconds. Default: 3600 (1 hour). */
208
- redisTtl?: number;
209
- }
210
- interface ShippingActions {
211
- getShippingRates: (toAddress: ShippingAddress, weight: number, serviceCodes?: string[]) => Promise<ListResult<TShippingMethod>>;
212
- }
213
- /**
214
- * @deprecated Use `createSiteActions()` instead. This factory will be removed in the next major version.
215
- *
216
- * Creates server-side shipping actions with Redis caching and edge cache support.
217
- *
218
- * Uses `withServerCache` which produces cache keys compatible with augur-hooks'
219
- * `withCache`, so server-prefetched data is shared with client-side hooks.
220
- *
221
- * @example
222
- * ```ts
223
- * // lib/shipping-actions.ts
224
- * import { createShippingActions } from "@simpleapps-com/augur-server";
225
- * import { getAugurClient } from "./augur-client";
226
- *
227
- * export const shippingActions = createShippingActions(getAugurClient(), {
228
- * fromAddress: {
229
- * address1: "123 Warehouse Ln",
230
- * city: "Chicago",
231
- * state: "IL",
232
- * postalCode: "60601",
233
- * },
234
- * });
235
- *
236
- * // In a server component:
237
- * const rates = await shippingActions.getShippingRates(
238
- * { address1: "456 Main St", city: "Denver", state: "CO", postalCode: "80202" },
239
- * 5.0,
240
- * );
241
- * ```
242
- */
243
- declare function createShippingActions(api: ShippingApiClient, config: ShippingActionsConfig): ShippingActions;
244
-
245
- /** Derived from augur-api SDK — keeps types in sync automatically. */
246
- type JoomlaApiClient = Pick<AugurAPI, "joomla">;
247
- interface JoomlaActionsConfig {
248
- /** Cache key prefix (e.g. "ampro:"). Default: "". */
249
- cachePrefix?: string;
250
- /** CDN edge cache value passed to SDK. Default: 1 (hour). */
251
- edgeCache?: EdgeCacheValue;
252
- /** Redis TTL for Joomla lookups in seconds. Default: 3600 (1 hour). */
253
- redisTtl?: number;
254
- }
255
- interface NormalizedUserProfile {
256
- id: string;
257
- name: string;
258
- email: string;
259
- customerId: string;
260
- permissions: string[];
261
- }
262
- interface JoomlaActions {
263
- getJoomlaContent: {
264
- (articleId: number): Promise<TJoomlaContent>;
265
- (articleId: number | string, options: {
266
- alias: string;
267
- catId?: number;
268
- }): Promise<TJoomlaContent>;
269
- };
270
- getJoomlaContentList: (params?: Record<string, unknown>) => Promise<ListResult<TJoomlaContent>>;
271
- getJoomlaMenu: {
272
- (params?: Record<string, unknown>): Promise<ListResult<TMenu>>;
273
- (parentId: number, menuType: string): Promise<ListResult<TMenu>>;
274
- };
275
- getJoomlaMenuDoc: (menuId: number | string) => Promise<MenuItem>;
276
- getUserProfile: (userId: number | string) => Promise<NormalizedUserProfile>;
277
- verifyPassword: (username: string, password: string) => Promise<TPasswordVerification>;
278
- }
279
- /**
280
- * @deprecated Use `createSiteActions()` instead. This factory will be removed in the next major version.
281
- *
282
- * Creates server-side Joomla content actions with Redis caching and edge cache support.
283
- *
284
- * Uses `withServerCache` which produces cache keys compatible with augur-hooks'
285
- * `withCache`, so server-prefetched data is shared with client-side hooks.
286
- *
287
- * @example
288
- * ```ts
289
- * // lib/joomla-actions.ts
290
- * import { createJoomlaActions } from "@simpleapps-com/augur-server";
291
- * import { getAugurClient } from "./augur-client";
292
- *
293
- * export const joomlaActions = createJoomlaActions(getAugurClient(), {
294
- * cachePrefix: "ampro:",
295
- * });
296
- *
297
- * // In a server component:
298
- * const article = await joomlaActions.getJoomlaContent(42);
299
- * const articles = await joomlaActions.getJoomlaContentList({ catid: 5 });
300
- * ```
301
- */
302
- declare function createJoomlaActions(api: JoomlaApiClient, config?: JoomlaActionsConfig): JoomlaActions;
303
-
304
- /** Derived from augur-api SDK — keeps types in sync automatically. */
305
- type SmartyStreetsApiClient = Pick<AugurAPI, "smartyStreets">;
306
- interface SmartyStreetsActionsConfig {
307
- /** Cache key prefix (e.g. "ampro:"). Default: "". */
308
- cachePrefix?: string;
309
- }
310
- /** Standardized response from address validation. */
311
- interface AddressValidationResult {
312
- data: TSmartyStreets | undefined;
313
- status: "success" | "not_found" | "error";
314
- error?: {
315
- message: string;
316
- };
317
- }
318
- interface SmartyStreetsActions {
319
- validateAddress: (params: Record<string, unknown>) => Promise<AddressValidationResult>;
320
- }
321
- /**
322
- * @deprecated Use `createSiteActions()` instead. This factory will be removed in the next major version.
323
- *
324
- * Creates server-side SmartyStreets actions for address validation.
325
- *
326
- * Note: Address validation is a real-time operation and does NOT use caching.
327
- * Each call hits the SmartyStreets API directly to ensure up-to-date results.
328
- *
329
- * @example
330
- * ```ts
331
- * import { createSmartyStreetsActions } from "@simpleapps-com/augur-server";
332
- * import { getAugurClient } from "./augur-client";
333
- *
334
- * export const smartyStreetsActions = createSmartyStreetsActions(getAugurClient());
335
- *
336
- * const result = await smartyStreetsActions.validateAddress({
337
- * address1: "123 Main St",
338
- * city: "Provo",
339
- * state: "UT",
340
- * postalCode: "84606",
341
- * });
342
- * if (result.status === "success") {
343
- * console.log(result.data); // TSmartyStreets
344
- * }
345
- * ```
346
- */
347
- declare function createSmartyStreetsActions(api: SmartyStreetsApiClient, config?: SmartyStreetsActionsConfig): SmartyStreetsActions;
348
-
349
- export { type AddressValidationResult as A, type GetItemCategoryOptions as G, type ItemActions as I, type JoomlaActions as J, type NormalizedUserProfile as N, type PaginatedResult as P, type SearchActions as S, type ItemActionsConfig as a, type ItemsApiClient as b, type JoomlaActionsConfig as c, type JoomlaApiClient as d, type SearchActionsConfig as e, type SearchApiClient as f, type SearchPage as g, type ShippingActions as h, type ShippingActionsConfig as i, type ShippingAddress as j, type ShippingApiClient as k, type SmartyStreetsActions as l, type SmartyStreetsActionsConfig as m, type SmartyStreetsApiClient as n, createItemActions as o, createJoomlaActions as p, createSearchActions as q, createShippingActions as r, createSmartyStreetsActions as s, paginateOffset as t };