@robosystems/client 2.5.2 → 2.6.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 (41) hide show
  1. package/artifacts/InvestorClient.d.ts +7 -1
  2. package/artifacts/InvestorClient.js +24 -14
  3. package/artifacts/InvestorClient.ts +46 -27
  4. package/artifacts/LedgerClient.d.ts +23 -17
  5. package/artifacts/LedgerClient.js +116 -123
  6. package/artifacts/LedgerClient.ts +180 -242
  7. package/artifacts/OperationClient.js +24 -1
  8. package/artifacts/OperationClient.ts +24 -1
  9. package/artifacts/OperatorClient.d.ts +10 -0
  10. package/artifacts/OperatorClient.js +72 -17
  11. package/artifacts/OperatorClient.ts +79 -21
  12. package/artifacts/QueryClient.d.ts +2 -1
  13. package/artifacts/QueryClient.js +17 -58
  14. package/artifacts/QueryClient.ts +21 -68
  15. package/artifacts/SSEClient.d.ts +1 -0
  16. package/artifacts/SSEClient.js +56 -7
  17. package/artifacts/SSEClient.ts +57 -7
  18. package/artifacts/config.js +18 -4
  19. package/artifacts/config.ts +18 -4
  20. package/artifacts/graphql/client.d.ts +10 -0
  21. package/artifacts/graphql/client.js +29 -21
  22. package/artifacts/graphql/client.ts +34 -23
  23. package/artifacts/index.d.ts +2 -2
  24. package/artifacts/index.js +6 -6
  25. package/artifacts/index.ts +8 -8
  26. package/artifacts/rest.d.ts +22 -0
  27. package/artifacts/rest.js +27 -0
  28. package/artifacts/rest.ts +54 -0
  29. package/artifacts/retry.js +8 -3
  30. package/artifacts/retry.ts +8 -3
  31. package/package.json +9 -1
  32. package/sdk/sdk.gen.d.ts +2 -2
  33. package/sdk/sdk.gen.js +2 -2
  34. package/sdk/sdk.gen.ts +2 -2
  35. package/sdk/types.gen.d.ts +21 -13
  36. package/sdk/types.gen.ts +21 -13
  37. package/sdk.gen.d.ts +2 -2
  38. package/sdk.gen.js +2 -2
  39. package/sdk.gen.ts +2 -2
  40. package/types.gen.d.ts +21 -13
  41. package/types.gen.ts +21 -13
@@ -165,10 +165,39 @@ function createTimeoutFetch(timeoutMs: number): typeof fetch {
165
165
  * sending a JWT as `X-API-Key` or an API key as Bearer both 401.
166
166
  */
167
167
  function applyAuthHeader(headers: Headers, token: string): void {
168
- if (token.startsWith('rfs')) {
169
- headers.set('X-API-Key', token)
170
- } else {
171
- headers.set('Authorization', `Bearer ${token}`)
168
+ for (const [name, value] of Object.entries(authHeaderFor(token))) {
169
+ headers.set(name, value)
170
+ }
171
+ }
172
+
173
+ /** The auth header for a credential — see {@link applyAuthHeader} for the rule. */
174
+ export function authHeaderFor(token: string): Record<string, string> {
175
+ return token.startsWith('rfs') ? { 'X-API-Key': token } : { Authorization: `Bearer ${token}` }
176
+ }
177
+
178
+ /**
179
+ * The credential for one request: the `tokenProvider` result when one is
180
+ * configured (`null` means send unauthenticated), otherwise the static
181
+ * `token`. A throwing provider fails the request fast — the caller meant
182
+ * to authenticate, and an unauthenticated request would surface as a
183
+ * confusing 401 far from the real failure (matches the Python client).
184
+ */
185
+ export async function resolveCredential(
186
+ config: Pick<GraphQLClientConfig, 'token' | 'tokenProvider'>
187
+ ): Promise<string | null> {
188
+ if (!config.tokenProvider) {
189
+ return config.token ?? null
190
+ }
191
+ try {
192
+ return (await config.tokenProvider()) ?? null
193
+ } catch (err) {
194
+ const detail = err instanceof Error ? err.message : String(err)
195
+ throw new Error(
196
+ `RoboSystems SDK: tokenProvider threw while resolving the request credential (${detail}). ` +
197
+ 'Fix the tokenProvider passed in the client config (or via setSDKClientConfig) so it ' +
198
+ 'returns the current token, or null to send an unauthenticated (cookie-based) request.',
199
+ { cause: err }
200
+ )
172
201
  }
173
202
  }
174
203
 
@@ -204,25 +233,7 @@ export function createGraphQLClient(config: GraphQLClientConfig, graphId: string
204
233
  credentials: config.credentials,
205
234
  fetch: timeoutFetch,
206
235
  requestMiddleware: async (request) => {
207
- let token: string | null | undefined
208
- try {
209
- token = await providerFn()
210
- } catch (err) {
211
- // Fail fast — a throwing provider means the caller *intended*
212
- // to authenticate but couldn't produce a credential. Sending
213
- // the request unauthenticated would surface as a confusing
214
- // 401 far from the real failure. (Matches the Python client,
215
- // which raises when its credential is missing.) A provider
216
- // that deliberately has no credential should return `null`
217
- // instead — that still sends an unauthenticated request.
218
- const detail = err instanceof Error ? err.message : String(err)
219
- throw new Error(
220
- `RoboSystems SDK: tokenProvider threw while resolving the request credential (${detail}). ` +
221
- 'Fix the tokenProvider passed in the client config (or via setSDKClientConfig) so it ' +
222
- 'returns the current token, or null to send an unauthenticated (cookie-based) request.',
223
- { cause: err }
224
- )
225
- }
236
+ const token = await resolveCredential({ tokenProvider: providerFn })
226
237
  if (!token) {
227
238
  return request
228
239
  }
@@ -23,8 +23,8 @@ export interface RoboSystemsClientConfig {
23
23
  */
24
24
  token?: string;
25
25
  /**
26
- * Dynamic credential callback invoked on every GraphQL request and
27
- * every SSE connect. When set, JWT refreshes are picked up
26
+ * Dynamic credential callback invoked on every GraphQL request, every
27
+ * facade REST write, and every SSE connect. When set, JWT refreshes are picked up
28
28
  * automatically — no need to rebuild or clear cached clients after a
29
29
  * refresh. Browser sessions need this: the backend revokes the previous
30
30
  * JWT on each refresh, so a static `token` captured at construction
@@ -54,10 +54,10 @@ class RoboSystemsClients {
54
54
  constructor(config = {}) {
55
55
  // Get base URL from SDK client config or use provided/default
56
56
  const sdkConfig = client_gen_1.client.getConfig();
57
- // Facade REST calls run through the generated ops, which share this
58
- // module-level client — its `fetch` is the only interception point,
59
- // since the ops take no per-call transport. A caller that already
60
- // supplied one keeps it; we never override an explicit choice.
57
+ // Facade REST calls run through the generated ops on this module-level
58
+ // client. They pass their own baseUrl, credential and headers per call,
59
+ // but the transport is still this client's `fetch`. A caller that
60
+ // already supplied one keeps it; we never override an explicit choice.
61
61
  if (!sdkConfig.fetch) {
62
62
  client_gen_1.client.setConfig({
63
63
  fetch: (0, retry_1.createRetryingFetch)({
@@ -78,8 +78,8 @@ class RoboSystemsClients {
78
78
  token,
79
79
  tokenProvider,
80
80
  headers: config.headers,
81
- maxRetries: config.maxRetries || 5,
82
- retryDelay: config.retryDelay || 1000,
81
+ maxRetries: config.maxRetries ?? 5,
82
+ retryDelay: config.retryDelay ?? 1000,
83
83
  timeout: config.timeout,
84
84
  };
85
85
  // Every client that opens an SSE stream gets the tokenProvider too:
@@ -47,8 +47,8 @@ export interface RoboSystemsClientConfig {
47
47
  */
48
48
  token?: string
49
49
  /**
50
- * Dynamic credential callback invoked on every GraphQL request and
51
- * every SSE connect. When set, JWT refreshes are picked up
50
+ * Dynamic credential callback invoked on every GraphQL request, every
51
+ * facade REST write, and every SSE connect. When set, JWT refreshes are picked up
52
52
  * automatically — no need to rebuild or clear cached clients after a
53
53
  * refresh. Browser sessions need this: the backend revokes the previous
54
54
  * JWT on each refresh, so a static `token` captured at construction
@@ -95,10 +95,10 @@ export class RoboSystemsClients {
95
95
  // Get base URL from SDK client config or use provided/default
96
96
  const sdkConfig = client.getConfig()
97
97
 
98
- // Facade REST calls run through the generated ops, which share this
99
- // module-level client — its `fetch` is the only interception point,
100
- // since the ops take no per-call transport. A caller that already
101
- // supplied one keeps it; we never override an explicit choice.
98
+ // Facade REST calls run through the generated ops on this module-level
99
+ // client. They pass their own baseUrl, credential and headers per call,
100
+ // but the transport is still this client's `fetch`. A caller that
101
+ // already supplied one keeps it; we never override an explicit choice.
102
102
  if (!sdkConfig.fetch) {
103
103
  client.setConfig({
104
104
  fetch: createRetryingFetch({
@@ -122,8 +122,8 @@ export class RoboSystemsClients {
122
122
  token,
123
123
  tokenProvider,
124
124
  headers: config.headers,
125
- maxRetries: config.maxRetries || 5,
126
- retryDelay: config.retryDelay || 1000,
125
+ maxRetries: config.maxRetries ?? 5,
126
+ retryDelay: config.retryDelay ?? 1000,
127
127
  timeout: config.timeout,
128
128
  }
129
129
 
@@ -0,0 +1,22 @@
1
+ /**
2
+ * Per-call transport options for the facades' REST calls.
3
+ *
4
+ * The generated ops default to the module-level `client` from
5
+ * `../sdk/client.gen`, which knows nothing of a facade's own `baseUrl` or
6
+ * credential. Facade REST calls (writes, Cypher queries, operator runs,
7
+ * operation status) pass these options per call instead, so they reach
8
+ * the same server, with the same credential, as the facade's GraphQL
9
+ * reads. They still run through the shared client, so
10
+ * its `fetch` (the retrying one `RoboSystemsClients` installs),
11
+ * interceptors and default headers keep applying underneath.
12
+ */
13
+ import type { GraphQLClientConfig } from './graphql/client';
14
+ export interface RestCallOptions {
15
+ baseUrl: string;
16
+ headers: Record<string, string>;
17
+ credentials?: 'include' | 'same-origin' | 'omit';
18
+ }
19
+ export type RestCallConfig = Pick<GraphQLClientConfig, 'baseUrl' | 'headers' | 'credentials' | 'token' | 'tokenProvider'>;
20
+ export declare function restCallOptions(config: RestCallConfig): Promise<RestCallOptions>;
21
+ /** Per-call options plus an `Idempotency-Key` header when one is given. */
22
+ export declare function withIdempotencyKey(options: RestCallOptions, idempotencyKey?: string | null): RestCallOptions;
@@ -0,0 +1,27 @@
1
+ 'use client';
2
+ "use strict";
3
+ Object.defineProperty(exports, "__esModule", { value: true });
4
+ exports.restCallOptions = restCallOptions;
5
+ exports.withIdempotencyKey = withIdempotencyKey;
6
+ const client_1 = require("./graphql/client");
7
+ async function restCallOptions(config) {
8
+ const headers = { ...(config.headers ?? {}) };
9
+ const token = await (0, client_1.resolveCredential)(config);
10
+ if (token) {
11
+ Object.assign(headers, (0, client_1.authHeaderFor)(token));
12
+ }
13
+ const options = { baseUrl: config.baseUrl.replace(/\/$/, ''), headers };
14
+ // Set only when configured: an explicit `undefined` would override the
15
+ // shared client's own `credentials`.
16
+ if (config.credentials) {
17
+ options.credentials = config.credentials;
18
+ }
19
+ return options;
20
+ }
21
+ /** Per-call options plus an `Idempotency-Key` header when one is given. */
22
+ function withIdempotencyKey(options, idempotencyKey) {
23
+ if (!idempotencyKey) {
24
+ return options;
25
+ }
26
+ return { ...options, headers: { ...options.headers, 'Idempotency-Key': idempotencyKey } };
27
+ }
@@ -0,0 +1,54 @@
1
+ 'use client'
2
+
3
+ /**
4
+ * Per-call transport options for the facades' REST calls.
5
+ *
6
+ * The generated ops default to the module-level `client` from
7
+ * `../sdk/client.gen`, which knows nothing of a facade's own `baseUrl` or
8
+ * credential. Facade REST calls (writes, Cypher queries, operator runs,
9
+ * operation status) pass these options per call instead, so they reach
10
+ * the same server, with the same credential, as the facade's GraphQL
11
+ * reads. They still run through the shared client, so
12
+ * its `fetch` (the retrying one `RoboSystemsClients` installs),
13
+ * interceptors and default headers keep applying underneath.
14
+ */
15
+
16
+ import type { GraphQLClientConfig } from './graphql/client'
17
+ import { authHeaderFor, resolveCredential } from './graphql/client'
18
+
19
+ export interface RestCallOptions {
20
+ baseUrl: string
21
+ headers: Record<string, string>
22
+ credentials?: 'include' | 'same-origin' | 'omit'
23
+ }
24
+
25
+ export type RestCallConfig = Pick<
26
+ GraphQLClientConfig,
27
+ 'baseUrl' | 'headers' | 'credentials' | 'token' | 'tokenProvider'
28
+ >
29
+
30
+ export async function restCallOptions(config: RestCallConfig): Promise<RestCallOptions> {
31
+ const headers: Record<string, string> = { ...(config.headers ?? {}) }
32
+ const token = await resolveCredential(config)
33
+ if (token) {
34
+ Object.assign(headers, authHeaderFor(token))
35
+ }
36
+ const options: RestCallOptions = { baseUrl: config.baseUrl.replace(/\/$/, ''), headers }
37
+ // Set only when configured: an explicit `undefined` would override the
38
+ // shared client's own `credentials`.
39
+ if (config.credentials) {
40
+ options.credentials = config.credentials
41
+ }
42
+ return options
43
+ }
44
+
45
+ /** Per-call options plus an `Idempotency-Key` header when one is given. */
46
+ export function withIdempotencyKey(
47
+ options: RestCallOptions,
48
+ idempotencyKey?: string | null
49
+ ): RestCallOptions {
50
+ if (!idempotencyKey) {
51
+ return options
52
+ }
53
+ return { ...options, headers: { ...options.headers, 'Idempotency-Key': idempotencyKey } }
54
+ }
@@ -100,20 +100,25 @@ function createRetryingFetch(options = {}) {
100
100
  const retryDelay = Math.max(1, options.retryDelay ?? exports.DEFAULT_RETRY_DELAY_MS);
101
101
  const inner = options.fetch;
102
102
  return async (input, init) => {
103
- const send = () => (inner ?? fetch)(input, init);
103
+ // The generated SDK passes a `Request`, whose body a send consumes.
104
+ // Each attempt sends a clone, so the original stays readable for the
105
+ // next one.
106
+ const template = typeof Request !== 'undefined' && input instanceof Request ? input : null;
107
+ const signal = init?.signal ?? template?.signal;
108
+ const send = () => (inner ?? fetch)(template && maxRetries > 0 ? template.clone() : input, init);
104
109
  let response = await send();
105
110
  for (let attempt = 0; attempt < maxRetries; attempt++) {
106
111
  if (!exports.RETRY_STATUS_CODES.has(response.status) || !isReplayable(init)) {
107
112
  return response;
108
113
  }
109
- if (init?.signal?.aborted) {
114
+ if (signal?.aborted) {
110
115
  return response;
111
116
  }
112
117
  const delay = backoffMs(attempt, retryDelay, retryAfterMs(response));
113
118
  // The rejection body goes unused, but leaving it undrained keeps
114
119
  // the connection pinned in some runtimes.
115
120
  await response.body?.cancel().catch(() => { });
116
- await sleep(delay, init?.signal);
121
+ await sleep(delay, signal);
117
122
  response = await send();
118
123
  }
119
124
  return response;
@@ -111,21 +111,26 @@ export function createRetryingFetch(options: RetryOptions = {}): typeof fetch {
111
111
  const inner = options.fetch
112
112
 
113
113
  return async (input, init) => {
114
- const send = () => (inner ?? fetch)(input, init)
114
+ // The generated SDK passes a `Request`, whose body a send consumes.
115
+ // Each attempt sends a clone, so the original stays readable for the
116
+ // next one.
117
+ const template = typeof Request !== 'undefined' && input instanceof Request ? input : null
118
+ const signal = init?.signal ?? template?.signal
119
+ const send = () => (inner ?? fetch)(template && maxRetries > 0 ? template.clone() : input, init)
115
120
  let response = await send()
116
121
 
117
122
  for (let attempt = 0; attempt < maxRetries; attempt++) {
118
123
  if (!RETRY_STATUS_CODES.has(response.status) || !isReplayable(init)) {
119
124
  return response
120
125
  }
121
- if (init?.signal?.aborted) {
126
+ if (signal?.aborted) {
122
127
  return response
123
128
  }
124
129
  const delay = backoffMs(attempt, retryDelay, retryAfterMs(response))
125
130
  // The rejection body goes unused, but leaving it undrained keeps
126
131
  // the connection pinned in some runtimes.
127
132
  await response.body?.cancel().catch(() => {})
128
- await sleep(delay, init?.signal)
133
+ await sleep(delay, signal)
129
134
  response = await send()
130
135
  }
131
136
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@robosystems/client",
3
- "version": "2.5.2",
3
+ "version": "2.6.0",
4
4
  "description": "TypeScript client library for the RoboSystems financial intelligence platform",
5
5
  "main": "index.js",
6
6
  "types": "index.d.ts",
@@ -169,5 +169,13 @@
169
169
  "@graphql-typed-document-node/core": "^3.2.0",
170
170
  "graphql": "^16.13.2",
171
171
  "graphql-request": "^7.4.0"
172
+ },
173
+ "peerDependencies": {
174
+ "react": ">=16.8.0"
175
+ },
176
+ "peerDependenciesMeta": {
177
+ "react": {
178
+ "optional": true
179
+ }
172
180
  }
173
181
  }
package/sdk/sdk.gen.d.ts CHANGED
@@ -1278,7 +1278,7 @@ export declare const unblockSourceGraph: <ThrowOnError extends boolean = false>(
1278
1278
  /**
1279
1279
  * Build Fact Grid
1280
1280
  *
1281
- * Queries LadybugDB `Fact` nodes by element qnames or canonical concepts, with filters for periods, entities, form, and fiscal context. Returns deduplicated facts plus the aspects they span — arranging them into a table is the consumer's job, since collapsing cells safely requires the full aspect signature. Works on both roboledger tenant graphs (post-materialization) and the SEC shared repository.
1281
+ * Queries LadybugDB `Fact` nodes by element qnames, with filters for periods and entities. Returns deduplicated facts plus the aspects they span — arranging them into a table is the consumer's job, since collapsing cells safely requires the full aspect signature. Works on both roboledger tenant graphs (post-materialization) and the SEC shared repository. Canonical concepts and the form and fiscal-period filters exist on shared repositories only: a ledger's graph carries none of them, and a query by them there is refused rather than answered with nothing.
1282
1282
  *
1283
1283
  * **Idempotency**: supply an `Idempotency-Key` header to make safe retries; replays within 24 hours return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.
1284
1284
  */
@@ -1310,7 +1310,7 @@ export declare const informationBlock: <ThrowOnError extends boolean = false>(op
1310
1310
  /**
1311
1311
  * Describe Filing
1312
1312
  *
1313
- * How one filing is laid out: entity, periods, statements and disclosures by role, axes, and its text — the Items of a 10-K or 10-Q and its largest text blocks, each with the character offset `read-text` pages from. On the SEC shared repository the filing is read from its public folder — its own document, from any processed year — and a `ticker` picks it: the latest annual report, narrowed by `fiscal_year` / `period_type`, or one `accession`, or with `form: 8-K` the latest earnings release and its exhibits. SEC only: a ledger files no document, and its sections read through `disclosures` and `information-block`.
1313
+ * How one filing is laid out: entity, periods, statements and disclosures by role, axes, and its text — the Items of a 10-K or 10-Q and its largest text blocks, each with the character offset `read-text` pages from. On the SEC shared repository the filing is read from its public folder — its own document, from any processed year — and a `ticker` picks it: the latest annual report, narrowed by `fiscal_year` / `period_type`, or one `accession`, or with `form: 8-K` the latest earnings release and its exhibits (`fiscal_year` is then the calendar year it was filed, and a CIK may stand in for the ticker). SEC only: a ledger files no document, and its sections read through `disclosures` and `information-block`.
1314
1314
  *
1315
1315
  * **Idempotency**: supply an `Idempotency-Key` header to make safe retries; replays within 24 hours return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.
1316
1316
  */
package/sdk/sdk.gen.js CHANGED
@@ -2640,7 +2640,7 @@ exports.unblockSourceGraph = unblockSourceGraph;
2640
2640
  /**
2641
2641
  * Build Fact Grid
2642
2642
  *
2643
- * Queries LadybugDB `Fact` nodes by element qnames or canonical concepts, with filters for periods, entities, form, and fiscal context. Returns deduplicated facts plus the aspects they span — arranging them into a table is the consumer's job, since collapsing cells safely requires the full aspect signature. Works on both roboledger tenant graphs (post-materialization) and the SEC shared repository.
2643
+ * Queries LadybugDB `Fact` nodes by element qnames, with filters for periods and entities. Returns deduplicated facts plus the aspects they span — arranging them into a table is the consumer's job, since collapsing cells safely requires the full aspect signature. Works on both roboledger tenant graphs (post-materialization) and the SEC shared repository. Canonical concepts and the form and fiscal-period filters exist on shared repositories only: a ledger's graph carries none of them, and a query by them there is refused rather than answered with nothing.
2644
2644
  *
2645
2645
  * **Idempotency**: supply an `Idempotency-Key` header to make safe retries; replays within 24 hours return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.
2646
2646
  */
@@ -2708,7 +2708,7 @@ exports.informationBlock = informationBlock;
2708
2708
  /**
2709
2709
  * Describe Filing
2710
2710
  *
2711
- * How one filing is laid out: entity, periods, statements and disclosures by role, axes, and its text — the Items of a 10-K or 10-Q and its largest text blocks, each with the character offset `read-text` pages from. On the SEC shared repository the filing is read from its public folder — its own document, from any processed year — and a `ticker` picks it: the latest annual report, narrowed by `fiscal_year` / `period_type`, or one `accession`, or with `form: 8-K` the latest earnings release and its exhibits. SEC only: a ledger files no document, and its sections read through `disclosures` and `information-block`.
2711
+ * How one filing is laid out: entity, periods, statements and disclosures by role, axes, and its text — the Items of a 10-K or 10-Q and its largest text blocks, each with the character offset `read-text` pages from. On the SEC shared repository the filing is read from its public folder — its own document, from any processed year — and a `ticker` picks it: the latest annual report, narrowed by `fiscal_year` / `period_type`, or one `accession`, or with `form: 8-K` the latest earnings release and its exhibits (`fiscal_year` is then the calendar year it was filed, and a CIK may stand in for the ticker). SEC only: a ledger files no document, and its sections read through `disclosures` and `information-block`.
2712
2712
  *
2713
2713
  * **Idempotency**: supply an `Idempotency-Key` header to make safe retries; replays within 24 hours return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.
2714
2714
  */
package/sdk/sdk.gen.ts CHANGED
@@ -2651,7 +2651,7 @@ export const unblockSourceGraph = <ThrowOnError extends boolean = false>(options
2651
2651
  /**
2652
2652
  * Build Fact Grid
2653
2653
  *
2654
- * Queries LadybugDB `Fact` nodes by element qnames or canonical concepts, with filters for periods, entities, form, and fiscal context. Returns deduplicated facts plus the aspects they span — arranging them into a table is the consumer's job, since collapsing cells safely requires the full aspect signature. Works on both roboledger tenant graphs (post-materialization) and the SEC shared repository.
2654
+ * Queries LadybugDB `Fact` nodes by element qnames, with filters for periods and entities. Returns deduplicated facts plus the aspects they span — arranging them into a table is the consumer's job, since collapsing cells safely requires the full aspect signature. Works on both roboledger tenant graphs (post-materialization) and the SEC shared repository. Canonical concepts and the form and fiscal-period filters exist on shared repositories only: a ledger's graph carries none of them, and a query by them there is refused rather than answered with nothing.
2655
2655
  *
2656
2656
  * **Idempotency**: supply an `Idempotency-Key` header to make safe retries; replays within 24 hours return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.
2657
2657
  */
@@ -2719,7 +2719,7 @@ export const informationBlock = <ThrowOnError extends boolean = false>(options:
2719
2719
  /**
2720
2720
  * Describe Filing
2721
2721
  *
2722
- * How one filing is laid out: entity, periods, statements and disclosures by role, axes, and its text — the Items of a 10-K or 10-Q and its largest text blocks, each with the character offset `read-text` pages from. On the SEC shared repository the filing is read from its public folder — its own document, from any processed year — and a `ticker` picks it: the latest annual report, narrowed by `fiscal_year` / `period_type`, or one `accession`, or with `form: 8-K` the latest earnings release and its exhibits. SEC only: a ledger files no document, and its sections read through `disclosures` and `information-block`.
2722
+ * How one filing is laid out: entity, periods, statements and disclosures by role, axes, and its text — the Items of a 10-K or 10-Q and its largest text blocks, each with the character offset `read-text` pages from. On the SEC shared repository the filing is read from its public folder — its own document, from any processed year — and a `ticker` picks it: the latest annual report, narrowed by `fiscal_year` / `period_type`, or one `accession`, or with `form: 8-K` the latest earnings release and its exhibits (`fiscal_year` is then the calendar year it was filed, and a CIK may stand in for the ticker). SEC only: a ledger files no document, and its sections read through `disclosures` and `information-block`.
2723
2723
  *
2724
2724
  * **Idempotency**: supply an `Idempotency-Key` header to make safe retries; replays within 24 hours return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.
2725
2725
  */
@@ -158,6 +158,12 @@ export type AnalyticalStatementFactRow = {
158
158
  * Value
159
159
  */
160
160
  value?: number | null;
161
+ /**
162
+ * Unit
163
+ *
164
+ * The fact's unit, e.g. `USD` or `USD/shares`. A line a filer reports in two units (its own currency and a US-dollar translation) comes back once per unit.
165
+ */
166
+ unit?: string | null;
161
167
  /**
162
168
  * Start Date
163
169
  */
@@ -3302,7 +3308,7 @@ export type CreateViewRequest = {
3302
3308
  /**
3303
3309
  * Canonical Concepts
3304
3310
  *
3305
- * Canonical concept names (e.g., 'revenue', 'net_income'). Matches all mapped qnames.
3311
+ * Canonical concept names (e.g., 'revenue', 'net_income'). Matches all mapped qnames. Shared repositories only.
3306
3312
  */
3307
3313
  canonical_concepts?: Array<string>;
3308
3314
  /**
@@ -3326,19 +3332,19 @@ export type CreateViewRequest = {
3326
3332
  /**
3327
3333
  * Form
3328
3334
  *
3329
- * Filter by SEC filing form type (e.g., '10-K', '10-Q')
3335
+ * Filter by SEC filing form type (e.g., '10-K', '10-Q'). Shared repositories only.
3330
3336
  */
3331
3337
  form?: string | null;
3332
3338
  /**
3333
3339
  * Fiscal Year
3334
3340
  *
3335
- * Filter by fiscal year (e.g., 2024)
3341
+ * Filter by fiscal year (e.g., 2024). Shared repositories only.
3336
3342
  */
3337
3343
  fiscal_year?: number | null;
3338
3344
  /**
3339
3345
  * Fiscal Period
3340
3346
  *
3341
- * Filter by fiscal period (e.g., 'FY', 'Q1', 'Q2', 'Q3')
3347
+ * Filter by fiscal period (e.g., 'FY', 'Q1', 'Q2', 'Q3'). Shared repositories only.
3342
3348
  */
3343
3349
  fiscal_period?: string | null;
3344
3350
  /**
@@ -3350,7 +3356,7 @@ export type CreateViewRequest = {
3350
3356
  /**
3351
3357
  * Include Summary
3352
3358
  *
3353
- * Include summary statistics per element
3359
+ * Include summary statistics per element. An element reported in more than one unit has none.
3354
3360
  */
3355
3361
  include_summary?: boolean;
3356
3362
  /**
@@ -4221,7 +4227,7 @@ export type DescribeFilingRequest = {
4221
4227
  /**
4222
4228
  * Form
4223
4229
  *
4224
- * SEC only, with ticker: '8-K' reads the latest earnings release
4230
+ * SEC only, with ticker: '8-K' reads the latest earnings release, or with fiscal_year the latest filed in that calendar year
4225
4231
  */
4226
4232
  form?: string | null;
4227
4233
  };
@@ -5859,12 +5865,10 @@ export type FilingLinks = {
5859
5865
  } | null;
5860
5866
  /**
5861
5867
  * Manifest
5868
+ *
5869
+ * Every file in the filing's public folder, with its URL
5862
5870
  */
5863
5871
  manifest?: string | null;
5864
- /**
5865
- * Folder
5866
- */
5867
- folder?: string | null;
5868
5872
  /**
5869
5873
  * Edgar
5870
5874
  *
@@ -13997,7 +14001,7 @@ export type ReadTextRequest = {
13997
14001
  /**
13998
14002
  * Form
13999
14003
  *
14000
- * SEC only, with ticker: '8-K' reads the latest earnings release
14004
+ * SEC only, with ticker: '8-K' reads the latest earnings release, or with fiscal_year the latest filed in that calendar year
14001
14005
  */
14002
14006
  form?: string | null;
14003
14007
  /**
@@ -15148,7 +15152,7 @@ export type ReopenPeriodOperation = {
15148
15152
  /**
15149
15153
  * Period
15150
15154
  *
15151
- * Period to reopen, in YYYY-MM. Any closed period may be reopened. Reopening the current `closed_through` retreats it by one month; reopening an earlier period leaves `closed_through` where it is (a prior-period adjustment), and its re-close restores the period without moving the pointer.
15155
+ * Period to reopen, in YYYY-MM. Only the latest closed period (the current `closed_through`) can be reopened, and reopening it retreats `closed_through` by one month. To reach an earlier period, reopen the later ones first, latest to earliest.
15152
15156
  */
15153
15157
  period: string;
15154
15158
  };
@@ -16183,6 +16187,10 @@ export type SearchHit = {
16183
16187
  * Form Type
16184
16188
  */
16185
16189
  form_type?: string | null;
16190
+ /**
16191
+ * Accession Number
16192
+ */
16193
+ accession_number?: string | null;
16186
16194
  /**
16187
16195
  * Xbrl Elements
16188
16196
  */
@@ -16371,7 +16379,7 @@ export type SearchTextRequest = {
16371
16379
  /**
16372
16380
  * Form
16373
16381
  *
16374
- * SEC only, with ticker: '8-K' reads the latest earnings release
16382
+ * SEC only, with ticker: '8-K' reads the latest earnings release, or with fiscal_year the latest filed in that calendar year
16375
16383
  */
16376
16384
  form?: string | null;
16377
16385
  /**
package/sdk/types.gen.ts CHANGED
@@ -166,6 +166,12 @@ export type AnalyticalStatementFactRow = {
166
166
  * Value
167
167
  */
168
168
  value?: number | null;
169
+ /**
170
+ * Unit
171
+ *
172
+ * The fact's unit, e.g. `USD` or `USD/shares`. A line a filer reports in two units (its own currency and a US-dollar translation) comes back once per unit.
173
+ */
174
+ unit?: string | null;
169
175
  /**
170
176
  * Start Date
171
177
  */
@@ -3383,7 +3389,7 @@ export type CreateViewRequest = {
3383
3389
  /**
3384
3390
  * Canonical Concepts
3385
3391
  *
3386
- * Canonical concept names (e.g., 'revenue', 'net_income'). Matches all mapped qnames.
3392
+ * Canonical concept names (e.g., 'revenue', 'net_income'). Matches all mapped qnames. Shared repositories only.
3387
3393
  */
3388
3394
  canonical_concepts?: Array<string>;
3389
3395
  /**
@@ -3407,19 +3413,19 @@ export type CreateViewRequest = {
3407
3413
  /**
3408
3414
  * Form
3409
3415
  *
3410
- * Filter by SEC filing form type (e.g., '10-K', '10-Q')
3416
+ * Filter by SEC filing form type (e.g., '10-K', '10-Q'). Shared repositories only.
3411
3417
  */
3412
3418
  form?: string | null;
3413
3419
  /**
3414
3420
  * Fiscal Year
3415
3421
  *
3416
- * Filter by fiscal year (e.g., 2024)
3422
+ * Filter by fiscal year (e.g., 2024). Shared repositories only.
3417
3423
  */
3418
3424
  fiscal_year?: number | null;
3419
3425
  /**
3420
3426
  * Fiscal Period
3421
3427
  *
3422
- * Filter by fiscal period (e.g., 'FY', 'Q1', 'Q2', 'Q3')
3428
+ * Filter by fiscal period (e.g., 'FY', 'Q1', 'Q2', 'Q3'). Shared repositories only.
3423
3429
  */
3424
3430
  fiscal_period?: string | null;
3425
3431
  /**
@@ -3431,7 +3437,7 @@ export type CreateViewRequest = {
3431
3437
  /**
3432
3438
  * Include Summary
3433
3439
  *
3434
- * Include summary statistics per element
3440
+ * Include summary statistics per element. An element reported in more than one unit has none.
3435
3441
  */
3436
3442
  include_summary?: boolean;
3437
3443
  /**
@@ -4330,7 +4336,7 @@ export type DescribeFilingRequest = {
4330
4336
  /**
4331
4337
  * Form
4332
4338
  *
4333
- * SEC only, with ticker: '8-K' reads the latest earnings release
4339
+ * SEC only, with ticker: '8-K' reads the latest earnings release, or with fiscal_year the latest filed in that calendar year
4334
4340
  */
4335
4341
  form?: string | null;
4336
4342
  };
@@ -6005,12 +6011,10 @@ export type FilingLinks = {
6005
6011
  } | null;
6006
6012
  /**
6007
6013
  * Manifest
6014
+ *
6015
+ * Every file in the filing's public folder, with its URL
6008
6016
  */
6009
6017
  manifest?: string | null;
6010
- /**
6011
- * Folder
6012
- */
6013
- folder?: string | null;
6014
6018
  /**
6015
6019
  * Edgar
6016
6020
  *
@@ -14336,7 +14340,7 @@ export type ReadTextRequest = {
14336
14340
  /**
14337
14341
  * Form
14338
14342
  *
14339
- * SEC only, with ticker: '8-K' reads the latest earnings release
14343
+ * SEC only, with ticker: '8-K' reads the latest earnings release, or with fiscal_year the latest filed in that calendar year
14340
14344
  */
14341
14345
  form?: string | null;
14342
14346
  /**
@@ -15513,7 +15517,7 @@ export type ReopenPeriodOperation = {
15513
15517
  /**
15514
15518
  * Period
15515
15519
  *
15516
- * Period to reopen, in YYYY-MM. Any closed period may be reopened. Reopening the current `closed_through` retreats it by one month; reopening an earlier period leaves `closed_through` where it is (a prior-period adjustment), and its re-close restores the period without moving the pointer.
15520
+ * Period to reopen, in YYYY-MM. Only the latest closed period (the current `closed_through`) can be reopened, and reopening it retreats `closed_through` by one month. To reach an earlier period, reopen the later ones first, latest to earliest.
15517
15521
  */
15518
15522
  period: string;
15519
15523
  };
@@ -16575,6 +16579,10 @@ export type SearchHit = {
16575
16579
  * Form Type
16576
16580
  */
16577
16581
  form_type?: string | null;
16582
+ /**
16583
+ * Accession Number
16584
+ */
16585
+ accession_number?: string | null;
16578
16586
  /**
16579
16587
  * Xbrl Elements
16580
16588
  */
@@ -16766,7 +16774,7 @@ export type SearchTextRequest = {
16766
16774
  /**
16767
16775
  * Form
16768
16776
  *
16769
- * SEC only, with ticker: '8-K' reads the latest earnings release
16777
+ * SEC only, with ticker: '8-K' reads the latest earnings release, or with fiscal_year the latest filed in that calendar year
16770
16778
  */
16771
16779
  form?: string | null;
16772
16780
  /**
package/sdk.gen.d.ts CHANGED
@@ -1278,7 +1278,7 @@ export declare const unblockSourceGraph: <ThrowOnError extends boolean = false>(
1278
1278
  /**
1279
1279
  * Build Fact Grid
1280
1280
  *
1281
- * Queries LadybugDB `Fact` nodes by element qnames or canonical concepts, with filters for periods, entities, form, and fiscal context. Returns deduplicated facts plus the aspects they span — arranging them into a table is the consumer's job, since collapsing cells safely requires the full aspect signature. Works on both roboledger tenant graphs (post-materialization) and the SEC shared repository.
1281
+ * Queries LadybugDB `Fact` nodes by element qnames, with filters for periods and entities. Returns deduplicated facts plus the aspects they span — arranging them into a table is the consumer's job, since collapsing cells safely requires the full aspect signature. Works on both roboledger tenant graphs (post-materialization) and the SEC shared repository. Canonical concepts and the form and fiscal-period filters exist on shared repositories only: a ledger's graph carries none of them, and a query by them there is refused rather than answered with nothing.
1282
1282
  *
1283
1283
  * **Idempotency**: supply an `Idempotency-Key` header to make safe retries; replays within 24 hours return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.
1284
1284
  */
@@ -1310,7 +1310,7 @@ export declare const informationBlock: <ThrowOnError extends boolean = false>(op
1310
1310
  /**
1311
1311
  * Describe Filing
1312
1312
  *
1313
- * How one filing is laid out: entity, periods, statements and disclosures by role, axes, and its text — the Items of a 10-K or 10-Q and its largest text blocks, each with the character offset `read-text` pages from. On the SEC shared repository the filing is read from its public folder — its own document, from any processed year — and a `ticker` picks it: the latest annual report, narrowed by `fiscal_year` / `period_type`, or one `accession`, or with `form: 8-K` the latest earnings release and its exhibits. SEC only: a ledger files no document, and its sections read through `disclosures` and `information-block`.
1313
+ * How one filing is laid out: entity, periods, statements and disclosures by role, axes, and its text — the Items of a 10-K or 10-Q and its largest text blocks, each with the character offset `read-text` pages from. On the SEC shared repository the filing is read from its public folder — its own document, from any processed year — and a `ticker` picks it: the latest annual report, narrowed by `fiscal_year` / `period_type`, or one `accession`, or with `form: 8-K` the latest earnings release and its exhibits (`fiscal_year` is then the calendar year it was filed, and a CIK may stand in for the ticker). SEC only: a ledger files no document, and its sections read through `disclosures` and `information-block`.
1314
1314
  *
1315
1315
  * **Idempotency**: supply an `Idempotency-Key` header to make safe retries; replays within 24 hours return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.
1316
1316
  */