@simpleapps-com/augur-server 2.4.0 → 2026.11.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.
- package/EXPORTS.md +30 -73
- package/README.md +29 -198
- package/dist/actions/agr-info.d.ts +44 -0
- package/dist/actions/agr-info.d.ts.map +1 -0
- package/dist/actions/agr-site.d.ts +38 -0
- package/dist/actions/agr-site.d.ts.map +1 -0
- package/dist/actions/agr-work.d.ts +29 -0
- package/dist/actions/agr-work.d.ts.map +1 -0
- package/dist/actions/avalara.d.ts +38 -0
- package/dist/actions/avalara.d.ts.map +1 -0
- package/dist/actions/basecamp2.d.ts +48 -0
- package/dist/actions/basecamp2.d.ts.map +1 -0
- package/dist/actions/brand-folder.d.ts +39 -0
- package/dist/actions/brand-folder.d.ts.map +1 -0
- package/dist/actions/commerce.d.ts +58 -0
- package/dist/actions/commerce.d.ts.map +1 -0
- package/dist/actions/customers.d.ts +45 -0
- package/dist/actions/customers.d.ts.map +1 -0
- package/dist/actions/favorites.d.ts +21 -0
- package/dist/actions/favorites.d.ts.map +1 -0
- package/dist/actions/gregorovich.d.ts +35 -0
- package/dist/actions/gregorovich.d.ts.map +1 -0
- package/dist/actions/items.d.ts +81 -0
- package/dist/actions/items.d.ts.map +1 -0
- package/dist/actions/joomla.d.ts +60 -0
- package/dist/actions/joomla.d.ts.map +1 -0
- package/dist/actions/legacy.d.ts +46 -0
- package/dist/actions/legacy.d.ts.map +1 -0
- package/dist/actions/logistics.d.ts +41 -0
- package/dist/actions/logistics.d.ts.map +1 -0
- package/dist/actions/orders.d.ts +37 -0
- package/dist/actions/orders.d.ts.map +1 -0
- package/dist/actions/p21-apis.d.ts +34 -0
- package/dist/actions/p21-apis.d.ts.map +1 -0
- package/dist/actions/p21-core.d.ts +47 -0
- package/dist/actions/p21-core.d.ts.map +1 -0
- package/dist/actions/p21-pim.d.ts +37 -0
- package/dist/actions/p21-pim.d.ts.map +1 -0
- package/dist/actions/p21-sism.d.ts +38 -0
- package/dist/actions/p21-sism.d.ts.map +1 -0
- package/dist/actions/payments.d.ts +39 -0
- package/dist/actions/payments.d.ts.map +1 -0
- package/dist/actions/pricing.d.ts +46 -0
- package/dist/actions/pricing.d.ts.map +1 -0
- package/dist/actions/search.d.ts +62 -0
- package/dist/actions/search.d.ts.map +1 -0
- package/dist/actions/shipping.d.ts +57 -0
- package/dist/actions/shipping.d.ts.map +1 -0
- package/dist/actions/site.d.ts +142 -0
- package/dist/actions/site.d.ts.map +1 -0
- package/dist/actions/smarty-streets.d.ts +45 -0
- package/dist/actions/smarty-streets.d.ts.map +1 -0
- package/dist/actions/vmi.d.ts +45 -0
- package/dist/actions/vmi.d.ts.map +1 -0
- package/dist/actions/wishlists.d.ts +29 -0
- package/dist/actions/wishlists.d.ts.map +1 -0
- package/dist/api-handler.d.ts +25 -0
- package/dist/api-handler.d.ts.map +1 -0
- package/dist/api.d.ts +2 -26
- package/dist/api.d.ts.map +1 -0
- package/dist/api.js +19 -14
- package/dist/api.js.map +1 -1
- package/dist/auth.d.ts +10 -12
- package/dist/auth.d.ts.map +1 -0
- package/dist/auth.js +2 -2
- package/dist/cache/redis-client.d.ts +18 -0
- package/dist/cache/redis-client.d.ts.map +1 -0
- package/dist/cache/with-cache.d.ts +17 -0
- package/dist/cache/with-cache.d.ts.map +1 -0
- package/dist/{chunk-PIYHMA6F.js → chunk-6CSVIBHQ.js} +15 -18
- package/dist/chunk-6CSVIBHQ.js.map +1 -0
- package/dist/{chunk-ALTIINP6.js → chunk-A4IVBK6P.js} +30 -6
- package/dist/chunk-A4IVBK6P.js.map +1 -0
- package/dist/{chunk-KHFEDL47.js → chunk-INVDQQ7T.js} +18 -12
- package/dist/chunk-INVDQQ7T.js.map +1 -0
- package/dist/{chunk-26WZBC4F.js → chunk-LX7SJJOU.js} +275 -667
- package/dist/chunk-LX7SJJOU.js.map +1 -0
- package/dist/chunk-OBWQSGB6.js +205 -0
- package/dist/chunk-OBWQSGB6.js.map +1 -0
- package/dist/{chunk-2NL4QKJN.js → chunk-UVGG74FO.js} +31 -30
- package/dist/chunk-UVGG74FO.js.map +1 -0
- package/dist/duration.d.ts +16 -0
- package/dist/duration.d.ts.map +1 -0
- package/dist/environment.d.ts +10 -0
- package/dist/environment.d.ts.map +1 -0
- package/dist/hooks.d.ts +8 -10
- package/dist/hooks.d.ts.map +1 -0
- package/dist/hooks.js +3 -3
- package/dist/hooks.js.map +1 -1
- package/dist/index.d.ts +16 -125
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +9 -7
- package/dist/index.js.map +1 -1
- package/dist/pagination.d.ts +32 -0
- package/dist/pagination.d.ts.map +1 -0
- package/dist/query-action.d.ts +15 -117
- package/dist/query-action.d.ts.map +1 -0
- package/dist/query-action.js +3 -3
- package/dist/query-options-helper.d.ts +34 -0
- package/dist/query-options-helper.d.ts.map +1 -0
- package/dist/query.js +1 -2
- package/dist/recaptcha.d.ts +6 -0
- package/dist/recaptcha.d.ts.map +1 -0
- package/dist/rules.d.ts +230 -0
- package/dist/rules.d.ts.map +1 -0
- package/dist/scoped-client-key.d.ts +9 -0
- package/dist/scoped-client-key.d.ts.map +1 -0
- package/dist/sdk-call.d.ts +66 -0
- package/dist/sdk-call.d.ts.map +1 -0
- package/dist/sdk-client-store.d.ts +250 -0
- package/dist/sdk-client-store.d.ts.map +1 -0
- package/dist/server-actions.d.ts +2 -0
- package/dist/server-actions.d.ts.map +1 -0
- package/dist/server-query-client.d.ts +19 -0
- package/dist/server-query-client.d.ts.map +1 -0
- package/dist/{server-site-registry-CdBfczOj.d.ts → server-site-registry.d.ts} +7 -9
- package/dist/server-site-registry.d.ts.map +1 -0
- package/dist/{site.d.ts → server-site.d.ts} +11 -16
- package/dist/server-site.d.ts.map +1 -0
- package/dist/site-actions-store.d.ts +27 -0
- package/dist/site-actions-store.d.ts.map +1 -0
- package/dist/site.js +15 -14
- package/dist/site.js.map +1 -1
- package/dist/testing.d.ts +9 -12
- package/dist/testing.d.ts.map +1 -0
- package/dist/testing.js +7 -27
- package/dist/testing.js.map +1 -1
- package/dist/utils/batch-fetch.d.ts +7 -0
- package/dist/utils/batch-fetch.d.ts.map +1 -0
- package/llms.txt +72 -51
- package/package.json +30 -20
- package/dist/actions.d.ts +0 -2
- package/dist/chunk-26WZBC4F.js.map +0 -1
- package/dist/chunk-2NL4QKJN.js.map +0 -1
- package/dist/chunk-ALTIINP6.js.map +0 -1
- package/dist/chunk-DGUM43GV.js +0 -11
- package/dist/chunk-DGUM43GV.js.map +0 -1
- package/dist/chunk-KHFEDL47.js.map +0 -1
- package/dist/chunk-PIYHMA6F.js.map +0 -1
- package/dist/query.d.ts +0 -35
- package/dist/site-BjSFqufX.d.ts +0 -469
package/dist/rules.d.ts
ADDED
|
@@ -0,0 +1,230 @@
|
|
|
1
|
+
import type { Millis, Seconds } from "./duration";
|
|
2
|
+
/**
|
|
3
|
+
* The siteId of a bearer's client_id claim (`<n>|<siteId>`): the text after the first "|", when
|
|
4
|
+
* there is one and it is non-empty. The prefix is not checked.
|
|
5
|
+
*
|
|
6
|
+
* @ensures exactly the model's ClientIdSiteId on a string claim
|
|
7
|
+
*/
|
|
8
|
+
export declare function clientIdSiteIdOf(clientId: string): string | null;
|
|
9
|
+
/** A session's siteId and bearer token, as minted, or refused. */
|
|
10
|
+
export type Mint = {
|
|
11
|
+
kind: "minted";
|
|
12
|
+
siteId: string;
|
|
13
|
+
token: string;
|
|
14
|
+
} | {
|
|
15
|
+
kind: "refused";
|
|
16
|
+
};
|
|
17
|
+
/**
|
|
18
|
+
* getSessionCredentials' mint, once the secret and the decoded session are in hand: a valid
|
|
19
|
+
* siteId (augur-api's `isSiteId`, checked by the caller), a non-empty token, and the bearer's
|
|
20
|
+
* client_id siteId (`""` for none: `clientIdSiteIdOf` never gives `""`) equal to it.
|
|
21
|
+
*
|
|
22
|
+
* @ensures exactly the model's MintCredentials with a secret and a decoded session
|
|
23
|
+
*/
|
|
24
|
+
export declare function mintedCredentials(siteIdOk: boolean, targetSiteId: string, token: string, bearerSiteId: string): Mint;
|
|
25
|
+
/**
|
|
26
|
+
* Whether there is another page: from the total when one is given, else a full page.
|
|
27
|
+
*
|
|
28
|
+
* @ensures exactly the model's HasMore
|
|
29
|
+
*/
|
|
30
|
+
export declare function hasMoreOf(page: number, limit: number, total: number | undefined, itemCount: number): boolean;
|
|
31
|
+
/**
|
|
32
|
+
* The next page's cursor: page + 1 while there is more.
|
|
33
|
+
*
|
|
34
|
+
* @ensures exactly the model's NextCursor given HasMore
|
|
35
|
+
*/
|
|
36
|
+
export declare function nextCursorOf(hasMore: boolean, page: number): number | undefined;
|
|
37
|
+
/** The deployment environment. */
|
|
38
|
+
export type Env = "development" | "staging" | "production";
|
|
39
|
+
/**
|
|
40
|
+
* DEPLOYMENT_ENV first; then the server's NODE_ENV; then the browser's host (substring). A missing
|
|
41
|
+
* variable is "".
|
|
42
|
+
*
|
|
43
|
+
* @ensures exactly the model's EnvOf
|
|
44
|
+
*/
|
|
45
|
+
export declare function envOf(deploymentEnv: string, isServer: boolean, nodeEnv: string, host: string): Env;
|
|
46
|
+
/**
|
|
47
|
+
* On the server: development only for NODE_ENV "development".
|
|
48
|
+
*
|
|
49
|
+
* @ensures result = development ⟺ nodeEnv = "development", else production
|
|
50
|
+
*/
|
|
51
|
+
export declare function serverEnvOf(nodeEnv: string): Env;
|
|
52
|
+
/**
|
|
53
|
+
* In the browser: localhost or 127.0.0.1 anywhere in the host is development, agr-hosting.dev
|
|
54
|
+
* staging, anything else production.
|
|
55
|
+
*
|
|
56
|
+
* @ensures exactly the model's host rule
|
|
57
|
+
*/
|
|
58
|
+
export declare function hostEnvOf(host: string): Env;
|
|
59
|
+
/** The API route's outcome for a request. */
|
|
60
|
+
export type ApiOutcome = "forbidden" | "bad-json" | "bad-method-path" | "bad-args" | "run";
|
|
61
|
+
/**
|
|
62
|
+
* A present, non-empty Sec-Fetch-Site other than same-origin is refused (a missing one, `""`
|
|
63
|
+
* from the caller, passes).
|
|
64
|
+
*
|
|
65
|
+
* @ensures result ⟺ fetchSite ∉ {"", "same-origin"}
|
|
66
|
+
*/
|
|
67
|
+
export declare function isCrossOrigin(fetchSite: string): boolean;
|
|
68
|
+
/**
|
|
69
|
+
* The body's outcome: JSON, then a non-empty methodPath string, then an args array.
|
|
70
|
+
*
|
|
71
|
+
* @ensures exactly the model's ApiOutcomeOf past the origin check
|
|
72
|
+
*/
|
|
73
|
+
export declare function bodyOutcomeOf(jsonOk: boolean, methodPathOk: boolean, argsIsArray: boolean): ApiOutcome;
|
|
74
|
+
/**
|
|
75
|
+
* An outcome's HTTP status: 403, 400 for a bad body, 200 to run.
|
|
76
|
+
*
|
|
77
|
+
* @ensures exactly the model's ApiStatus
|
|
78
|
+
*/
|
|
79
|
+
export declare function apiStatusOf(o: ApiOutcome): number;
|
|
80
|
+
/**
|
|
81
|
+
* A refusal's response text ("" to run).
|
|
82
|
+
*
|
|
83
|
+
* @ensures each refusal has its fixed text
|
|
84
|
+
*/
|
|
85
|
+
export declare function apiMessageOf(o: ApiOutcome): string;
|
|
86
|
+
/**
|
|
87
|
+
* The Redis TTL for a cache tier: none for staleTime 0, the long TTL from an hour up, else the
|
|
88
|
+
* standard one. `staleTime` is React Query's `Millis`, the TTLs Redis's `Seconds`; the hour is
|
|
89
|
+
* compared in milliseconds.
|
|
90
|
+
*
|
|
91
|
+
* @ensures exactly the model's TtlFor
|
|
92
|
+
*/
|
|
93
|
+
export declare function ttlFor(staleTime: Millis, redisTtl: Seconds, longRedisTtl: Seconds): Seconds | null;
|
|
94
|
+
/** The Redis circuit breaker's state: consecutive failures, and when it closes (0 = closed). */
|
|
95
|
+
export interface Circuit {
|
|
96
|
+
failures: number;
|
|
97
|
+
openUntil: Millis;
|
|
98
|
+
}
|
|
99
|
+
/** The circuit's answer at a time: whether it is open, and its state after the check. */
|
|
100
|
+
export interface CircuitAnswer {
|
|
101
|
+
open: boolean;
|
|
102
|
+
next: Circuit;
|
|
103
|
+
}
|
|
104
|
+
/**
|
|
105
|
+
* isCircuitOpen at `now`: closed at openUntil 0; past it, reset and closed; else open.
|
|
106
|
+
*
|
|
107
|
+
* @ensures exactly the model's CircuitCheck
|
|
108
|
+
*/
|
|
109
|
+
export declare function circuitCheck(c: Circuit, now: Millis): CircuitAnswer;
|
|
110
|
+
/**
|
|
111
|
+
* Whether a failure count opens the circuit: five in a row.
|
|
112
|
+
*
|
|
113
|
+
* @ensures result ⟺ failures ≥ 5
|
|
114
|
+
*/
|
|
115
|
+
export declare function opensAt(failures: number): boolean;
|
|
116
|
+
/**
|
|
117
|
+
* A failure counts; from the threshold on the circuit opens for a minute from now.
|
|
118
|
+
*
|
|
119
|
+
* @ensures exactly the model's RecordFailure
|
|
120
|
+
*/
|
|
121
|
+
export declare function recordFailureOf(c: Circuit, now: Millis): Circuit;
|
|
122
|
+
/**
|
|
123
|
+
* A success clears the failure count and leaves openUntil.
|
|
124
|
+
*
|
|
125
|
+
* @ensures exactly the model's RecordSuccess
|
|
126
|
+
*/
|
|
127
|
+
export declare function recordSuccessOf(c: Circuit): Circuit;
|
|
128
|
+
/**
|
|
129
|
+
* authorize's verified flag: exactly the text "true".
|
|
130
|
+
*
|
|
131
|
+
* @ensures result ⟺ s = "true"
|
|
132
|
+
*/
|
|
133
|
+
export declare function verifiedFlag(s: string): boolean;
|
|
134
|
+
/**
|
|
135
|
+
* reCAPTCHA passes only with a secret, an ok response and the reply's optional `success` exactly
|
|
136
|
+
* true (the score is not read).
|
|
137
|
+
*
|
|
138
|
+
* @ensures exactly the model's RecaptchaOk, success read as `=== true`
|
|
139
|
+
*/
|
|
140
|
+
export declare function recaptchaOk(hasSecret: boolean, httpOk: boolean, success: boolean | undefined): boolean;
|
|
141
|
+
/**
|
|
142
|
+
* A customer id is used only above 0; anything else (NaN included, at the caller) is 0.
|
|
143
|
+
*
|
|
144
|
+
* @ensures result = n when n > 0, else 0
|
|
145
|
+
*/
|
|
146
|
+
export declare function positiveOrZero(n: number): number;
|
|
147
|
+
/**
|
|
148
|
+
* The category page size: 24 when none (or 0) is given.
|
|
149
|
+
*
|
|
150
|
+
* @ensures exactly the model's ItemsLimit, a missing limit as 0
|
|
151
|
+
*/
|
|
152
|
+
export declare function itemsLimitOf(limit: number | undefined): number;
|
|
153
|
+
/** How queryAction resolves its client. */
|
|
154
|
+
export type Resolution = "scoped" | "global" | "uninit";
|
|
155
|
+
/**
|
|
156
|
+
* resolveClient: scoped when credentials minted and a scoped client was made; else the global
|
|
157
|
+
* client when one is registered (also for a valid session without a factory); else none.
|
|
158
|
+
*
|
|
159
|
+
* @ensures exactly the model's ResolveClient
|
|
160
|
+
*/
|
|
161
|
+
export declare function resolutionOf(minted: boolean, scopedMade: boolean, hasGlobal: boolean): Resolution;
|
|
162
|
+
/** The scoped-client slot's decision. */
|
|
163
|
+
export type SlotDecision = "hit" | "mint" | "no-client";
|
|
164
|
+
/**
|
|
165
|
+
* getOrCreateScopedClient's single slot: a hit when it holds this key; else a new client when a
|
|
166
|
+
* factory is registered; else none. An empty slot is "" at the caller, which no key equals (a
|
|
167
|
+
* key holds a NUL).
|
|
168
|
+
*
|
|
169
|
+
* @ensures exactly the model's SlotDecisionOf
|
|
170
|
+
*/
|
|
171
|
+
export declare function slotDecisionOf(slotKey: string, key: string, hasFactory: boolean): SlotDecision;
|
|
172
|
+
/**
|
|
173
|
+
* parseMethodPath: a non-empty path, in the allowlist when one is registered (permissive by
|
|
174
|
+
* default); `listed` is the caller's Set lookup.
|
|
175
|
+
*
|
|
176
|
+
* @ensures exactly the model's ApprovePath
|
|
177
|
+
*/
|
|
178
|
+
export declare function approvePath(path: string, hasAllowlist: boolean, listed: boolean): boolean;
|
|
179
|
+
/**
|
|
180
|
+
* queryAction caches a call only through a wrapper, and only for a read leaf (augur-core's
|
|
181
|
+
* `isReadMethod`, checked by the caller).
|
|
182
|
+
*
|
|
183
|
+
* @ensures exactly the model's UsesCache
|
|
184
|
+
*/
|
|
185
|
+
export declare function usesCache(hasWrapper: boolean, isRead: boolean): boolean;
|
|
186
|
+
/**
|
|
187
|
+
* The scoped cache prefix: the session's siteId and ":".
|
|
188
|
+
*
|
|
189
|
+
* @ensures exactly the model's ScopedPrefix
|
|
190
|
+
*/
|
|
191
|
+
export declare function scopedPrefix(siteId: string): string;
|
|
192
|
+
/**
|
|
193
|
+
* withServerCache caches when the TTL is not 0 (missing or NaN is 0 at the caller; a `Seconds`
|
|
194
|
+
* is never negative).
|
|
195
|
+
*
|
|
196
|
+
* @ensures exactly the model's ShouldCache
|
|
197
|
+
*/
|
|
198
|
+
export declare function shouldCache(ttl: Seconds): boolean;
|
|
199
|
+
/**
|
|
200
|
+
* The TTL a server cache call uses: a missing one (undefined or NaN, which the caller reads) is 0,
|
|
201
|
+
* as `!redisTtl` had it.
|
|
202
|
+
*
|
|
203
|
+
* @ensures exactly the model's CacheTtl
|
|
204
|
+
*/
|
|
205
|
+
export declare function cacheTtlOf(missing: boolean, ttl: Seconds): Seconds;
|
|
206
|
+
/**
|
|
207
|
+
* getInvMastDoc's positional uid: kept above 0, else none.
|
|
208
|
+
*
|
|
209
|
+
* @ensures result = uid when uid > 0, else undefined
|
|
210
|
+
*/
|
|
211
|
+
export declare function docUidOf(uid: number): number | undefined;
|
|
212
|
+
/**
|
|
213
|
+
* The positional itemId is used only at uid 0 and when non-empty ("" for none, at the caller).
|
|
214
|
+
*
|
|
215
|
+
* @ensures result ⟺ uid = 0 ∧ itemId ≠ ""
|
|
216
|
+
*/
|
|
217
|
+
export declare function takesItemId(uid: number, itemId: string): boolean;
|
|
218
|
+
/**
|
|
219
|
+
* A doc call needs a uid (truthy at the caller) or a non-empty itemId.
|
|
220
|
+
*
|
|
221
|
+
* @ensures result ⟺ uidSet ∨ itemId ≠ ""
|
|
222
|
+
*/
|
|
223
|
+
export declare function hasDocKey(uidSet: boolean, itemId: string): boolean;
|
|
224
|
+
/**
|
|
225
|
+
* The configured payments mode, "live" by default.
|
|
226
|
+
*
|
|
227
|
+
* @ensures result = configured ?? "live"
|
|
228
|
+
*/
|
|
229
|
+
export declare function configuredModeOf(configured: string | undefined): string;
|
|
230
|
+
//# sourceMappingURL=rules.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../src/rules.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The key `siteId + "\0" + token`. Callers MUST pass a siteId with no NUL character
|
|
3
|
+
* (`getSessionCredentials` enforces `isSiteId`); with that, distinct pairs give distinct keys.
|
|
4
|
+
* A siteId with a NUL throws instead of returning a key that could collide.
|
|
5
|
+
*
|
|
6
|
+
* @throws TypeError when `siteId` contains a NUL character
|
|
7
|
+
*/
|
|
8
|
+
export declare function scopedClientKey(siteId: string, token: string): string;
|
|
9
|
+
//# sourceMappingURL=scoped-client-key.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"scoped-client-key.d.ts","sourceRoot":"","sources":["../src/scoped-client-key.ts"],"names":[],"mappings":"AAgCA;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAMrE"}
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
export type { EdgeCacheValue, ActionResult, ApiResult, ListResult, } from "@simpleapps-com/augur-core";
|
|
2
|
+
import type { ApiResult, ListResult } from "@simpleapps-com/augur-core";
|
|
3
|
+
/**
|
|
4
|
+
* Calls an Augur SDK method, forwarding all arguments with full type safety.
|
|
5
|
+
*
|
|
6
|
+
* With augur-api >= 0.9.6, SDK methods properly declare their `CacheParams`
|
|
7
|
+
* option (including `edgeCache`), so this wrapper preserves both parameter
|
|
8
|
+
* and return-type inference end-to-end.
|
|
9
|
+
*
|
|
10
|
+
* @example
|
|
11
|
+
* ```ts
|
|
12
|
+
* const result = await sdkCall(
|
|
13
|
+
* augurServices.items.invMast.get,
|
|
14
|
+
* invMastUid,
|
|
15
|
+
* { edgeCache: 4 },
|
|
16
|
+
* );
|
|
17
|
+
* ```
|
|
18
|
+
*/
|
|
19
|
+
export declare function sdkCall<TArgs extends unknown[], TResult>(method: (...args: TArgs) => Promise<TResult>, ...args: TArgs): Promise<TResult>;
|
|
20
|
+
/** The SDK response envelope fields the result helpers read. */
|
|
21
|
+
interface SdkEnvelope {
|
|
22
|
+
data?: unknown;
|
|
23
|
+
total?: number;
|
|
24
|
+
count?: number;
|
|
25
|
+
totalResults?: number;
|
|
26
|
+
message?: string;
|
|
27
|
+
status?: number;
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* Extracts an ApiResult from an SDK response, preserving envelope metadata.
|
|
31
|
+
* Use this for single-item endpoints where `data` is a single object.
|
|
32
|
+
*/
|
|
33
|
+
export declare function toApiResult<T>(response: SdkEnvelope): ApiResult<T>;
|
|
34
|
+
/**
|
|
35
|
+
* Extracts a ListResult from an SDK response, preserving envelope metadata.
|
|
36
|
+
* Use this for list endpoints where `data` is an array.
|
|
37
|
+
*/
|
|
38
|
+
export declare function toListResult<T>(response: SdkEnvelope): ListResult<T>;
|
|
39
|
+
export { unwrap, unwrapOr } from "@simpleapps-com/augur-utils";
|
|
40
|
+
export type { SafeActionResult } from "@simpleapps-com/augur-utils";
|
|
41
|
+
import type { SafeActionResult } from "@simpleapps-com/augur-utils";
|
|
42
|
+
/**
|
|
43
|
+
* Wraps an async function call with error handling, returning a
|
|
44
|
+
* `SafeActionResult<T>` instead of throwing.
|
|
45
|
+
*
|
|
46
|
+
* Use this to eliminate try/catch boilerplate in server actions.
|
|
47
|
+
* Reads that go through React Query should NOT use this — let errors
|
|
48
|
+
* propagate so React Query can handle retries and error state.
|
|
49
|
+
*
|
|
50
|
+
* @param fn — The async function to execute
|
|
51
|
+
* @param onError — Optional callback for logging/reporting
|
|
52
|
+
*
|
|
53
|
+
* @example
|
|
54
|
+
* ```ts
|
|
55
|
+
* const result = await safeAction(
|
|
56
|
+
* () => actions.commerce.addToCart(cartId, items),
|
|
57
|
+
* );
|
|
58
|
+
* if (result.ok) {
|
|
59
|
+
* // result.data is the response data (undefined for void actions)
|
|
60
|
+
* } else {
|
|
61
|
+
* // result.error is the error message
|
|
62
|
+
* }
|
|
63
|
+
* ```
|
|
64
|
+
*/
|
|
65
|
+
export declare function safeAction<T>(fn: () => Promise<T>, onError?: (error: Error) => void): Promise<SafeActionResult<T>>;
|
|
66
|
+
//# sourceMappingURL=sdk-call.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"sdk-call.d.ts","sourceRoot":"","sources":["../src/sdk-call.ts"],"names":[],"mappings":"AACA,YAAY,EACV,cAAc,EACd,YAAY,EACZ,SAAS,EACT,UAAU,GACX,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAExE;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,OAAO,CAAC,KAAK,SAAS,OAAO,EAAE,EAAE,OAAO,EAC5D,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,EAC5C,GAAG,IAAI,EAAE,KAAK,GACb,OAAO,CAAC,OAAO,CAAC,CAElB;AAED,gEAAgE;AAChE,UAAU,WAAW;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,QAAQ,EAAE,WAAW,GAAG,SAAS,CAAC,CAAC,CAAC,CASlE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,WAAW,GAAG,UAAU,CAAC,CAAC,CAAC,CASpE;AAGD,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAC/D,YAAY,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAEpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAChC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAC/B,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAS9B"}
|
|
@@ -0,0 +1,250 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Lightweight getter/setter for the raw SDK client instance, cache wrapper,
|
|
3
|
+
* auth secret, client factory, and scoped client cache.
|
|
4
|
+
*
|
|
5
|
+
* queryAction resolves method paths on the SDK client directly (not on
|
|
6
|
+
* SiteActions). This ensures the proxy pattern works end-to-end: the
|
|
7
|
+
* proxy generates SDK namespace paths (e.g. "pricing.priceEngine.get")
|
|
8
|
+
* which match the SDK client structure.
|
|
9
|
+
*
|
|
10
|
+
* The cache wrapper is a function registered by createServerSite() that
|
|
11
|
+
* wraps SDK calls with Redis caching. It captures withServerCache + config
|
|
12
|
+
* in its closure, so queryAction can use it without importing heavy deps.
|
|
13
|
+
*
|
|
14
|
+
* The auth secret, client factory, and scoped cache wrapper support
|
|
15
|
+
* per-request session credentials for multi-tenant apps. queryAction
|
|
16
|
+
* decodes the JWT from request cookies and creates scoped SDK clients
|
|
17
|
+
* when the session contains a targetSiteId + token.
|
|
18
|
+
*
|
|
19
|
+
* This module has ZERO imports from actions/site, cache/, or any factory.
|
|
20
|
+
* Same isolation constraints as site-actions-store.ts.
|
|
21
|
+
*/
|
|
22
|
+
/** Function that wraps an SDK call with server-side caching. */
|
|
23
|
+
export type SdkCallWrapper = (methodPath: string, sdkCall: () => Promise<unknown>, ...keyArgs: unknown[]) => Promise<unknown>;
|
|
24
|
+
/** Function that wraps an SDK call with server-side caching using a specific prefix. */
|
|
25
|
+
export type ScopedCacheWrapper = (prefix: string, methodPath: string, sdkCall: () => Promise<unknown>, ...keyArgs: unknown[]) => Promise<unknown>;
|
|
26
|
+
/** Function that creates a scoped SDK client with different credentials. */
|
|
27
|
+
export type ClientFactory = (siteId: string, bearerToken: string) => unknown;
|
|
28
|
+
declare const SessionSiteIdBrand: unique symbol;
|
|
29
|
+
declare const SessionBearerTokenBrand: unique symbol;
|
|
30
|
+
declare const SessionCredentialsBrand: unique symbol;
|
|
31
|
+
declare const ApprovedMethodPathBrand: unique symbol;
|
|
32
|
+
/**
|
|
33
|
+
* Site identifier extracted from a validated Auth.js session JWT cookie.
|
|
34
|
+
*
|
|
35
|
+
* Intended to be minted only by `getSessionCredentials` in query-action.ts.
|
|
36
|
+
*
|
|
37
|
+
* Brand strength: code-review signal, not type-system enforcement. TypeScript
|
|
38
|
+
* allows `value as SessionSiteId` casts, so audit `as SessionSiteId` usages
|
|
39
|
+
* to catch unintended mints — there should be exactly one, at the JWT mint
|
|
40
|
+
* point.
|
|
41
|
+
*/
|
|
42
|
+
export type SessionSiteId = string & {
|
|
43
|
+
readonly [SessionSiteIdBrand]: true;
|
|
44
|
+
};
|
|
45
|
+
/**
|
|
46
|
+
* Bearer token extracted from a validated Auth.js session JWT cookie.
|
|
47
|
+
* Same intended-mint and brand-strength caveat as {@link SessionSiteId}.
|
|
48
|
+
*/
|
|
49
|
+
export type SessionBearerToken = string & {
|
|
50
|
+
readonly [SessionBearerTokenBrand]: true;
|
|
51
|
+
};
|
|
52
|
+
/**
|
|
53
|
+
* Paired session credentials. Bundles `siteId` and `token` from the same
|
|
54
|
+
* validated session into one value so downstream functions can accept the
|
|
55
|
+
* pair as a unit, instead of two separate parameters that callers might
|
|
56
|
+
* accidentally mix across sessions.
|
|
57
|
+
*
|
|
58
|
+
* Intended to be minted only by `getSessionCredentials` in query-action.ts,
|
|
59
|
+
* which performs the cross-check that the bearer's `client_id` siteId
|
|
60
|
+
* matches `targetSiteId`. Anything that holds a `SessionCredentials` *was*
|
|
61
|
+
* cross-checked at mint time — provided the value came through that mint
|
|
62
|
+
* and not via a cast.
|
|
63
|
+
*
|
|
64
|
+
* Brand strength: same code-review signal as the field brands. `value as
|
|
65
|
+
* SessionCredentials` compiles. Audit `as SessionCredentials` usages — there
|
|
66
|
+
* should be exactly one, in `getSessionCredentials`.
|
|
67
|
+
*/
|
|
68
|
+
export type SessionCredentials = {
|
|
69
|
+
readonly siteId: SessionSiteId;
|
|
70
|
+
readonly token: SessionBearerToken;
|
|
71
|
+
readonly [SessionCredentialsBrand]: true;
|
|
72
|
+
};
|
|
73
|
+
/**
|
|
74
|
+
* SDK method path validated against the registered allowlist.
|
|
75
|
+
*
|
|
76
|
+
* Intended to be minted only by `parseMethodPath` below. Functions that walk
|
|
77
|
+
* the path into the SDK client (notably `resolveMethod`) demand this type
|
|
78
|
+
* so that an unvalidated string flowing into the walker is a compile error
|
|
79
|
+
* for code that respects the convention.
|
|
80
|
+
*
|
|
81
|
+
* Brand strength: code-review signal. `value as ApprovedMethodPath` compiles.
|
|
82
|
+
* Audit `as ApprovedMethodPath` usages — there should be one, in
|
|
83
|
+
* `parseMethodPath`.
|
|
84
|
+
*
|
|
85
|
+
* Scope of validation: this is a *site-level surface restriction*, not a
|
|
86
|
+
* security boundary. augur-api is the auth authority; the allowlist limits
|
|
87
|
+
* what the application's proxy will forward to the SDK, not what tokens are
|
|
88
|
+
* permitted to do. Useful for narrowing same-origin attack surface (XSS,
|
|
89
|
+
* malicious bundled deps); not a substitute for API-level authorization.
|
|
90
|
+
*/
|
|
91
|
+
export type ApprovedMethodPath = string & {
|
|
92
|
+
readonly [ApprovedMethodPathBrand]: true;
|
|
93
|
+
};
|
|
94
|
+
/** Register the raw SDK client instance. Called by createServerSite(). */
|
|
95
|
+
export declare function registerSdkClient(client: unknown): void;
|
|
96
|
+
/** Returns the registered SDK client, or null if not yet registered. */
|
|
97
|
+
export declare function getSdkClientOrNull(): unknown;
|
|
98
|
+
/**
|
|
99
|
+
* Register a cache wrapper for SDK calls. Called by createServerSite().
|
|
100
|
+
* The wrapper captures withServerCache + config in its closure so that
|
|
101
|
+
* queryAction can use Redis caching without importing heavy deps.
|
|
102
|
+
*/
|
|
103
|
+
export declare function registerSdkCallWrapper(wrapper: SdkCallWrapper): void;
|
|
104
|
+
/** Returns the registered cache wrapper, or null if not registered. */
|
|
105
|
+
export declare function getSdkCallWrapper(): SdkCallWrapper | null;
|
|
106
|
+
/** Register the auth secret for JWT decoding. Called by createServerSite(). */
|
|
107
|
+
export declare function registerAuthSecret(secret: string): void;
|
|
108
|
+
/** Returns the registered auth secret, or null if not registered. */
|
|
109
|
+
export declare function getAuthSecret(): string | null;
|
|
110
|
+
/** Register a factory that creates scoped SDK clients. Called by createServerSite(). */
|
|
111
|
+
export declare function registerClientFactory(factory: ClientFactory): void;
|
|
112
|
+
/** Returns the registered client factory, or null if not registered. */
|
|
113
|
+
export declare function getClientFactory(): ClientFactory | null;
|
|
114
|
+
/** Register a scoped cache wrapper that accepts a prefix. Called by createServerSite(). */
|
|
115
|
+
export declare function registerScopedCacheWrapper(wrapper: ScopedCacheWrapper): void;
|
|
116
|
+
/** Returns the registered scoped cache wrapper, or null if not registered. */
|
|
117
|
+
export declare function getScopedCacheWrapper(): ScopedCacheWrapper | null;
|
|
118
|
+
/**
|
|
119
|
+
* Returns a cached scoped client for the given credentials, or creates one
|
|
120
|
+
* via the registered factory. Caches the last credential pair so that
|
|
121
|
+
* multiple queryAction calls in the same request reuse the same client.
|
|
122
|
+
*
|
|
123
|
+
* Accepts `SessionCredentials` (a branded paired type) rather than two raw
|
|
124
|
+
* strings: well-behaved callers pass the pair as a unit, eliminating the
|
|
125
|
+
* "siteId from session A combined with token from session B" mistake at
|
|
126
|
+
* the type level — see {@link SessionCredentials} brand-strength caveat.
|
|
127
|
+
* The factory itself still receives strings (its signature is user-facing API).
|
|
128
|
+
*
|
|
129
|
+
* ## Trust
|
|
130
|
+
*
|
|
131
|
+
* @trusted credentials // the SessionCredentials brand carries the
|
|
132
|
+
* // bearer/session siteId cross-check discharged at
|
|
133
|
+
* // mint time by `getSessionCredentials`. This
|
|
134
|
+
* // function does NOT re-validate; if a non-mint
|
|
135
|
+
* // path produces a SessionCredentials value (via
|
|
136
|
+
* // `as` cast), this function will materialise a
|
|
137
|
+
* // client for whatever siteId + token are present
|
|
138
|
+
* // in the value. Audit `as SessionCredentials`
|
|
139
|
+
* // usages — there should be exactly one, in
|
|
140
|
+
* // getSessionCredentials.
|
|
141
|
+
*
|
|
142
|
+
* ## Decision (Property)
|
|
143
|
+
*
|
|
144
|
+
* let key = `${credentials.siteId}\0${credentials.token}` in
|
|
145
|
+
* result(credentials) =
|
|
146
|
+
* _scopedClient.client when _scopedClient?.key = key // cache hit
|
|
147
|
+
* factory(siteId, token) when factory ≠ null // mint + cache
|
|
148
|
+
* null when factory = null // uninitialised
|
|
149
|
+
*
|
|
150
|
+
* Three outcomes. Throws only if `credentials.siteId` contains a NUL
|
|
151
|
+
* (`scopedClientKey`), which the mint point rules out by `isSiteId`, so it
|
|
152
|
+
* is reachable only through an `as SessionCredentials` cast. Side effect on
|
|
153
|
+
* the mint path only:
|
|
154
|
+
* `_scopedClient` is replaced with `{key, client}` so the next call with
|
|
155
|
+
* the same credentials hits the cached branch. Minting implicitly evicts
|
|
156
|
+
* the previous `_scopedClient` value (single-slot semantics — see invariant).
|
|
157
|
+
*
|
|
158
|
+
* ## Invariant — null-byte key separator (machine-checked)
|
|
159
|
+
*
|
|
160
|
+
* The key is `scopedClientKey(siteId, token)` = `siteId + "\0" + token`
|
|
161
|
+
* (`scoped-client-key.ts`). Dafny proves (`ScopedClientKeyInjective`) that
|
|
162
|
+
* for two NUL-free siteIds, equal keys mean equal siteIds and equal tokens,
|
|
163
|
+
* so the cache cannot hand one credential pair another pair's client. Only
|
|
164
|
+
* the siteId has to be NUL-free; the token may contain anything.
|
|
165
|
+
*
|
|
166
|
+
* The precondition is enforced, not assumed: `getSessionCredentials`, the
|
|
167
|
+
* only mint point, refuses any `targetSiteId` that fails augur-api's
|
|
168
|
+
* `isSiteId` (`[a-z0-9_-]+`, machine-checked in augur-api), and
|
|
169
|
+
* `scopedClientKey` throws on a NUL rather than return a key that could
|
|
170
|
+
* collide. What is NOT proved: that no other code path casts a value to
|
|
171
|
+
* `SessionCredentials` (see the Trust note above).
|
|
172
|
+
*
|
|
173
|
+
* Do NOT change the separator to a character that could appear in a
|
|
174
|
+
* siteId; the proof is stated for NUL and would have to be redone.
|
|
175
|
+
*
|
|
176
|
+
* ## Invariant — single-slot cache (eviction is implicit)
|
|
177
|
+
*
|
|
178
|
+
* `_scopedClient` holds at most one entry. Minting a client for
|
|
179
|
+
* credentials A AFTER credentials B were cached evicts B unrecoverably;
|
|
180
|
+
* a later request with credentials B will call the factory again rather
|
|
181
|
+
* than retrieving the previously-minted client.
|
|
182
|
+
*
|
|
183
|
+
* This is intentional. Scoped clients are per-request shortcuts; the
|
|
184
|
+
* cache exists to let multiple queryAction calls within a single request
|
|
185
|
+
* share an SDK client without re-running the factory. Cross-request
|
|
186
|
+
* caching is NOT a goal — Next.js may or may not preserve module state
|
|
187
|
+
* across invocations, so any retention beyond the single slot is
|
|
188
|
+
* best-effort and MUST NOT be relied upon for correctness.
|
|
189
|
+
*
|
|
190
|
+
* A future refactor to multi-slot LRU would change this contract:
|
|
191
|
+
* per-credential client identity becomes ambiguous across requests, and
|
|
192
|
+
* eviction policy becomes security-relevant (e.g. oldest-out could re-mint
|
|
193
|
+
* a client immediately after a credential rotation, surfacing stale
|
|
194
|
+
* permissions to the next caller). Do not multi-slot this without
|
|
195
|
+
* re-deriving the contract — particularly the relationship to credential
|
|
196
|
+
* rotation and bearer-token revocation in augur-api.
|
|
197
|
+
*
|
|
198
|
+
* ## Postcondition — identity, not transformation
|
|
199
|
+
*
|
|
200
|
+
* result ≠ null ⟹ result is referentially identical to the value the
|
|
201
|
+
* factory returned for the matching credentials.
|
|
202
|
+
*
|
|
203
|
+
* The cache stores and serves the factory's exact return value. It does
|
|
204
|
+
* not wrap, transform, proxy, or copy the client. Consumers that mutate
|
|
205
|
+
* the returned client (e.g. setting per-request properties on a singleton
|
|
206
|
+
* field) will observe the mutation on subsequent cache hits within the
|
|
207
|
+
* same request — by design.
|
|
208
|
+
*/
|
|
209
|
+
export declare function getOrCreateScopedClient(credentials: SessionCredentials): unknown;
|
|
210
|
+
/**
|
|
211
|
+
* Register one or more SDK method paths the application is permitted to call
|
|
212
|
+
* through `queryAction`. Subsequent calls accumulate (idempotent on repeats).
|
|
213
|
+
*
|
|
214
|
+
* This is *site-level surface restriction*, not security. augur-api remains
|
|
215
|
+
* the auth authority; this primitive lets a site narrow its proxy's surface
|
|
216
|
+
* to the methods its UI actually wires up. Useful as defense-in-depth against
|
|
217
|
+
* same-origin XSS or compromised bundled deps POSTing arbitrary methodPaths
|
|
218
|
+
* to `/api/augur` — those calls will hit augur-api with the user's bearer
|
|
219
|
+
* (which augur-api will allow if the bearer is authorized), but the allowlist
|
|
220
|
+
* stops them from leaving the proxy in the first place.
|
|
221
|
+
*
|
|
222
|
+
* Permissive default: if `registerAllowedMethodPaths` is never called, all
|
|
223
|
+
* non-empty paths pass — the proxy behaves as a transparent forwarder, which
|
|
224
|
+
* is the package's design intent. Sites that want surface restriction opt in
|
|
225
|
+
* by calling this function.
|
|
226
|
+
*/
|
|
227
|
+
export declare function registerAllowedMethodPaths(paths: readonly string[]): void;
|
|
228
|
+
/**
|
|
229
|
+
* Returns true if the application has registered an allowlist via
|
|
230
|
+
* {@link registerAllowedMethodPaths}. When false, `parseMethodPath` operates
|
|
231
|
+
* in permissive mode (any non-empty string passes).
|
|
232
|
+
*/
|
|
233
|
+
export declare function isMethodPathAllowlistRegistered(): boolean;
|
|
234
|
+
/**
|
|
235
|
+
* Validate a candidate method path against the registered allowlist.
|
|
236
|
+
*
|
|
237
|
+
* - Returns the branded value if the path is a non-empty string AND
|
|
238
|
+
* (no allowlist is registered OR the path is in the allowlist).
|
|
239
|
+
* - Returns null if the path is not a non-empty string, or if an allowlist
|
|
240
|
+
* has been registered and the path is not in it.
|
|
241
|
+
*
|
|
242
|
+
* The brand on the return type is the only way internal code can produce an
|
|
243
|
+
* `ApprovedMethodPath`. Functions that walk the path into the SDK should
|
|
244
|
+
* accept `ApprovedMethodPath`, forcing the caller to discharge the validation.
|
|
245
|
+
*/
|
|
246
|
+
export declare function parseMethodPath(candidate: unknown): ApprovedMethodPath | null;
|
|
247
|
+
/** Clears the registered SDK client, wrapper, and session stores. Used in tests only. @internal */
|
|
248
|
+
export declare function clearSdkClient(): void;
|
|
249
|
+
export {};
|
|
250
|
+
//# sourceMappingURL=sdk-client-store.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"sdk-client-store.d.ts","sourceRoot":"","sources":["../src/sdk-client-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH,gEAAgE;AAChE,MAAM,MAAM,cAAc,GAAG,CAC3B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,EAC/B,GAAG,OAAO,EAAE,OAAO,EAAE,KAClB,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtB,wFAAwF;AACxF,MAAM,MAAM,kBAAkB,GAAG,CAC/B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,EAC/B,GAAG,OAAO,EAAE,OAAO,EAAE,KAClB,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtB,4EAA4E;AAC5E,MAAM,MAAM,aAAa,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC;AAE7E,OAAO,CAAC,MAAM,kBAAkB,EAAE,OAAO,MAAM,CAAC;AAChD,OAAO,CAAC,MAAM,uBAAuB,EAAE,OAAO,MAAM,CAAC;AACrD,OAAO,CAAC,MAAM,uBAAuB,EAAE,OAAO,MAAM,CAAC;AACrD,OAAO,CAAC,MAAM,uBAAuB,EAAE,OAAO,MAAM,CAAC;AAErD;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,kBAAkB,CAAC,EAAE,IAAI,CAAA;CAAE,CAAC;AAE7E;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,uBAAuB,CAAC,EAAE,IAAI,CAAA;CAAE,CAAC;AAEvF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC;IACnC,QAAQ,CAAC,CAAC,uBAAuB,CAAC,EAAE,IAAI,CAAC;CAC1C,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,uBAAuB,CAAC,EAAE,IAAI,CAAA;CAAE,CAAC;AAmBvF,0EAA0E;AAC1E,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAGvD;AAED,wEAAwE;AACxE,wBAAgB,kBAAkB,IAAI,OAAO,CAS5C;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CAGpE;AAED,uEAAuE;AACvE,wBAAgB,iBAAiB,IAAI,cAAc,GAAG,IAAI,CAEzD;AAED,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAGvD;AAED,qEAAqE;AACrE,wBAAgB,aAAa,IAAI,MAAM,GAAG,IAAI,CAE7C;AAED,wFAAwF;AACxF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAGlE;AAED,wEAAwE;AACxE,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,IAAI,CAEvD;AAED,2FAA2F;AAC3F,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAG5E;AAED,8EAA8E;AAC9E,wBAAgB,qBAAqB,IAAI,kBAAkB,GAAG,IAAI,CAEjE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0FG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,kBAAkB,GAAG,OAAO,CAWhF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAMzE;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,IAAI,OAAO,CAEzD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,OAAO,GAAG,kBAAkB,GAAG,IAAI,CAM7E;AAED,mGAAmG;AACnG,wBAAgB,cAAc,IAAI,IAAI,CAcrC"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"server-actions.d.ts","sourceRoot":"","sources":["../src/server-actions.ts"],"names":[],"mappings":"AAWA,YAAY,EAAE,gBAAgB,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
import { QueryClient } from "@tanstack/react-query";
|
|
2
|
+
/**
|
|
3
|
+
* Creates a server-side query client optimised for prefetching.
|
|
4
|
+
*
|
|
5
|
+
* - No persistence (server-only)
|
|
6
|
+
* - No GC timers (gcTime: Infinity), so the client is freed with the request
|
|
7
|
+
* - No retries (fail fast on server)
|
|
8
|
+
* - No refetching (server renders are one-shot)
|
|
9
|
+
*/
|
|
10
|
+
export declare function createServerQueryClient(): QueryClient;
|
|
11
|
+
/**
|
|
12
|
+
* Returns a per-request singleton QueryClient for React Server Components.
|
|
13
|
+
*
|
|
14
|
+
* React's `cache()` deduplicates calls within a single server request,
|
|
15
|
+
* so each request gets its own QueryClient while avoiding the cross-request
|
|
16
|
+
* state leakage that a module-level singleton would cause.
|
|
17
|
+
*/
|
|
18
|
+
export declare const getServerQueryClient: () => QueryClient;
|
|
19
|
+
//# sourceMappingURL=server-query-client.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"server-query-client.d.ts","sourceRoot":"","sources":["../src/server-query-client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAGpD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,IAAI,WAAW,CAerD;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,QAAa,WAAyC,CAAC"}
|
|
@@ -1,5 +1,4 @@
|
|
|
1
|
-
import {
|
|
2
|
-
|
|
1
|
+
import type { SiteActions } from "./actions/site";
|
|
3
2
|
/**
|
|
4
3
|
* Process-global storage for the site actions singleton.
|
|
5
4
|
*
|
|
@@ -13,7 +12,7 @@ import { S as SiteActions } from './site-BjSFqufX.js';
|
|
|
13
12
|
* `globalThis` on dynamic routes -- see vercel/next.js#74204).
|
|
14
13
|
*
|
|
15
14
|
* As a last resort, if both caches are empty, `getSiteActions()` will
|
|
16
|
-
* auto-initialize from `AUGUR_SITE_ID` + `
|
|
15
|
+
* auto-initialize from `AUGUR_SITE_ID` + `AUGUR_JWT` environment variables.
|
|
17
16
|
* This self-healing behaviour prevents crashes when Next.js loses the
|
|
18
17
|
* singleton across webpack bundle boundaries.
|
|
19
18
|
*/
|
|
@@ -21,21 +20,20 @@ import { S as SiteActions } from './site-BjSFqufX.js';
|
|
|
21
20
|
* Stores the site actions instance for use by server action exports.
|
|
22
21
|
* Called automatically by {@link createServerSite}.
|
|
23
22
|
*/
|
|
24
|
-
declare function registerSiteActions(actions: SiteActions): void;
|
|
23
|
+
export declare function registerSiteActions(actions: SiteActions): void;
|
|
25
24
|
/**
|
|
26
25
|
* Returns the registered site actions instance.
|
|
27
26
|
*
|
|
28
27
|
* Resolution order:
|
|
29
28
|
* 1. `globalThis` singleton (fastest, cross-bundle)
|
|
30
29
|
* 2. Module-level cache (survives globalThis resets)
|
|
31
|
-
* 3. Auto-init from `AUGUR_SITE_ID` + `
|
|
30
|
+
* 3. Auto-init from `AUGUR_SITE_ID` + `AUGUR_JWT` env vars (self-healing)
|
|
32
31
|
* 4. Throws if none of the above succeed
|
|
33
32
|
*/
|
|
34
|
-
declare function getSiteActions(): SiteActions;
|
|
33
|
+
export declare function getSiteActions(): SiteActions;
|
|
35
34
|
/**
|
|
36
35
|
* Clears the registered site actions. Used in tests only.
|
|
37
36
|
* @internal
|
|
38
37
|
*/
|
|
39
|
-
declare function clearSiteActions(): void;
|
|
40
|
-
|
|
41
|
-
export { clearSiteActions as c, getSiteActions as g, registerSiteActions as r };
|
|
38
|
+
export declare function clearSiteActions(): void;
|
|
39
|
+
//# sourceMappingURL=server-site-registry.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"server-site-registry.d.ts","sourceRoot":"","sources":["../src/server-site-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAelD;;;;;;;;;;;;;;;;GAgBG;AAEH;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAE9D;AAgCD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,IAAI,WAAW,CAU5C;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC"}
|