@opendatalabs/vana-sdk 3.22.0 → 3.23.0-pr.211.3227174

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 (79) hide show
  1. package/README.md +57 -0
  2. package/dist/auth/errors.cjs +1 -1
  3. package/dist/auth/web3-signed.cjs +1 -1
  4. package/dist/crypto/envelope/job-stream.test.d.ts +1 -0
  5. package/dist/crypto/envelope/job.cjs +818 -0
  6. package/dist/crypto/envelope/job.cjs.map +1 -0
  7. package/dist/crypto/envelope/job.d.ts +139 -0
  8. package/dist/crypto/envelope/job.js +792 -0
  9. package/dist/crypto/envelope/job.js.map +1 -0
  10. package/dist/direct/access-request-client.cjs +5 -1
  11. package/dist/direct/access-request-client.cjs.map +1 -1
  12. package/dist/direct/access-request-client.js +4 -0
  13. package/dist/direct/access-request-client.js.map +1 -1
  14. package/dist/direct/connect-flow.cjs +43 -1
  15. package/dist/direct/connect-flow.cjs.map +1 -1
  16. package/dist/direct/connect-flow.d.ts +12 -0
  17. package/dist/direct/connect-flow.js +43 -1
  18. package/dist/direct/connect-flow.js.map +1 -1
  19. package/dist/direct/controller.cjs +1 -1
  20. package/dist/direct/errors.cjs +1 -1
  21. package/dist/direct/personal-server-read.cjs +2 -2
  22. package/dist/direct/types.cjs.map +1 -1
  23. package/dist/direct/types.d.ts +7 -0
  24. package/dist/direct/types.js.map +1 -1
  25. package/dist/direct/use-direct-vana-connect.cjs +2 -1
  26. package/dist/direct/use-direct-vana-connect.cjs.map +1 -1
  27. package/dist/direct/use-direct-vana-connect.d.ts +3 -1
  28. package/dist/direct/use-direct-vana-connect.js +2 -1
  29. package/dist/direct/use-direct-vana-connect.js.map +1 -1
  30. package/dist/error-entry-points.test.d.ts +1 -0
  31. package/dist/errors.cjs +84 -0
  32. package/dist/errors.cjs.map +1 -1
  33. package/dist/errors.d.ts +133 -0
  34. package/dist/errors.js +73 -0
  35. package/dist/errors.js.map +1 -1
  36. package/dist/index.browser.d.ts +3 -0
  37. package/dist/index.browser.js +1143 -434
  38. package/dist/index.browser.js.map +4 -4
  39. package/dist/index.node.cjs +1801 -631
  40. package/dist/index.node.cjs.map +4 -4
  41. package/dist/index.node.d.ts +4 -0
  42. package/dist/index.node.js +1762 -522
  43. package/dist/index.node.js.map +4 -4
  44. package/dist/protocol/data-point-deletion.cjs +1 -1
  45. package/dist/protocol/derivative-questions.cjs +1 -1
  46. package/dist/protocol/derivative-status.cjs +1 -1
  47. package/dist/protocol/fixtures/moksha-identity.json +20 -0
  48. package/dist/protocol/gateway.cjs +1 -1
  49. package/dist/protocol/identity.cjs +224 -0
  50. package/dist/protocol/identity.cjs.map +1 -0
  51. package/dist/protocol/identity.d.ts +193 -0
  52. package/dist/protocol/identity.js +188 -0
  53. package/dist/protocol/identity.js.map +1 -0
  54. package/dist/protocol/identity.test.d.ts +1 -0
  55. package/dist/protocol/identity.vector.test.d.ts +1 -0
  56. package/dist/protocol/jobs-client.cjs +551 -0
  57. package/dist/protocol/jobs-client.cjs.map +1 -0
  58. package/dist/protocol/jobs-client.d.ts +169 -0
  59. package/dist/protocol/jobs-client.js +558 -0
  60. package/dist/protocol/jobs-client.js.map +1 -0
  61. package/dist/protocol/jobs-client.test.d.ts +1 -0
  62. package/dist/protocol/jobs.cjs +64 -0
  63. package/dist/protocol/jobs.cjs.map +1 -0
  64. package/dist/protocol/jobs.d.ts +193 -0
  65. package/dist/protocol/jobs.js +31 -0
  66. package/dist/protocol/jobs.js.map +1 -0
  67. package/dist/protocol/jobs.test.d.ts +1 -0
  68. package/dist/protocol/lineage.cjs +1 -1
  69. package/dist/protocol/personal-server-data.cjs +1 -1
  70. package/dist/protocol/personal-server-write.cjs +1 -1
  71. package/dist/protocol/write-request.cjs +1 -1
  72. package/dist/protocol/write-signer.cjs +1 -1
  73. package/dist/react.cjs.map +1 -1
  74. package/dist/react.d.ts +1 -1
  75. package/dist/react.js.map +1 -1
  76. package/dist/session-relay/client.cjs +1 -1
  77. package/dist/session-relay/errors.cjs +1 -1
  78. package/dist/session-relay/index.cjs +1 -1
  79. package/package.json +7 -1
@@ -0,0 +1,169 @@
1
+ /**
2
+ * Builder-side client for encrypted Gateway jobs.
3
+ *
4
+ * @remarks
5
+ * This Node-only client fetches an owner's sealed enclave identity, signs and
6
+ * seals raw-read work, submits it to the Gateway, polls builder-visible state,
7
+ * and decrypts the bound result with the builder private key.
8
+ *
9
+ * @category Protocol
10
+ */
11
+ import { type Address, type Hex, type LocalAccount } from "viem";
12
+ import type { ECIESProvider } from "../crypto/ecies/interface.js";
13
+ import { type JobResult, type JobState, type JobStatus, type ResultHandle } from "./jobs.js";
14
+ import { type WriteSignerSource } from "./write-signer.js";
15
+ /** A viem local account that exposes the public key required by job requests. */
16
+ export type JobsBuilderAccount = Extract<LocalAccount, WriteSignerSource>;
17
+ /** Configuration captured by {@link createJobsClient}. */
18
+ export interface JobsClientOptions {
19
+ /** Gateway base URL; its origin is the Web3Signed audience. */
20
+ gatewayUrl: string;
21
+ /** Vana chain ID used by the owner identity lookup. */
22
+ chainId: number;
23
+ /** Raw builder private key, used for signing and result decryption. */
24
+ builderPrivateKey?: Hex;
25
+ /**
26
+ * viem local account used for signing. Its public key supports submission,
27
+ * but without `builderPrivateKey` this client cannot decrypt results:
28
+ * `openResult` and `readRaw` reject while submit/status/wait remain usable.
29
+ */
30
+ builderAccount?: JobsBuilderAccount;
31
+ /** HTTP implementation; defaults to `globalThis.fetch`. */
32
+ fetch?: typeof fetch;
33
+ /** ECIES implementation; defaults to the Node provider. */
34
+ ecies?: ECIESProvider;
35
+ /** Clock used when constructing a job deadline. */
36
+ now?: () => Date;
37
+ }
38
+ /** Parameters for one encrypted raw-read submission. */
39
+ export interface SubmitRawReadParams {
40
+ /** Owner whose enclave executes the read. */
41
+ owner: Address;
42
+ /** Owner-issued builder grant. */
43
+ grantId: Hex;
44
+ /** Data scope to read. */
45
+ scope: string;
46
+ /** Exact record version to require, or `null` for an unpinned read. */
47
+ pinnedVersion?: string | null;
48
+ /** Requested deadline offset, clamped to the protocol maximum. */
49
+ deadlineSeconds?: number;
50
+ /** Gateway inline-wait seconds, clamped to `0..MAX_WAIT_SECONDS`. */
51
+ wait?: number;
52
+ }
53
+ /** Result of submitting an encrypted raw-read job. */
54
+ export interface SubmitRawReadResult {
55
+ /** Client-generated job UUID. */
56
+ jobId: string;
57
+ /** Current Gateway state. */
58
+ state: JobState;
59
+ /** Full status when the Gateway returned an inline 200 response. */
60
+ job?: JobStatus;
61
+ }
62
+ /** Polling controls for {@link JobsClient.waitForJob}. */
63
+ export interface WaitForJobOptions {
64
+ /** Total polling budget in milliseconds. */
65
+ timeoutMs?: number;
66
+ /** Delay between reads; values below `CLAIM_POLL_FLOOR_MS` are raised. */
67
+ pollMs?: number;
68
+ }
69
+ /** Expected plaintext bindings for {@link JobsClient.openResult}. */
70
+ export interface OpenJobResultOptions {
71
+ /** Bind the plaintext to this job id. */
72
+ expect: {
73
+ jobId: string;
74
+ scope?: string;
75
+ version?: string | null;
76
+ };
77
+ }
78
+ /** Parameters for the submit, wait, and decrypt convenience flow. */
79
+ export interface ReadRawParams extends SubmitRawReadParams, WaitForJobOptions {
80
+ }
81
+ /** Builder operations exposed by {@link createJobsClient}. */
82
+ export interface JobsClient {
83
+ /**
84
+ * Encrypt and submit a raw-read job.
85
+ *
86
+ * @param params - Owner, grant, scope, deadline, and inline-wait controls.
87
+ * @returns The job id and current state, plus inline status on HTTP 200.
88
+ * @throws {OwnerNotReadyError} When the owner identity is not sealed.
89
+ * @throws {JobsClientError} When the Gateway or transport rejects the call.
90
+ */
91
+ submitRawRead(params: SubmitRawReadParams): Promise<SubmitRawReadResult>;
92
+ /**
93
+ * Read one builder-visible job status.
94
+ *
95
+ * @param jobId - Client-generated job UUID.
96
+ * @returns The current job status.
97
+ * @throws {JobNotFoundError} When the job is absent or belongs to another builder.
98
+ * @throws {JobsClientError} For other Gateway or transport failures.
99
+ */
100
+ getJob(jobId: string): Promise<JobStatus>;
101
+ /**
102
+ * Poll until a job completes, fails, expires, or is cancelled.
103
+ *
104
+ * @param jobId - Job UUID to poll.
105
+ * @param options - Timeout and poll cadence.
106
+ * @returns The terminal job status.
107
+ * @throws {JobTimeoutError} When the caller or job deadline is exhausted.
108
+ */
109
+ waitForJob(jobId: string, options?: WaitForJobOptions): Promise<JobStatus>;
110
+ /**
111
+ * Fetch, decrypt, and validate a job result from object storage.
112
+ *
113
+ * @param handle - Object-storage location and integrity metadata.
114
+ * @param options - Expected plaintext job, scope, and version bindings.
115
+ * @returns The validated plaintext job result.
116
+ * @remarks Decryption requires `builderPrivateKey`; `builderAccount` alone
117
+ * only supports submission, status reads, and waiting.
118
+ * @throws {JobRejectedError} When a raw private key is unavailable.
119
+ * @throws {JobTransportError} When fetching the result object fails.
120
+ * @throws {JobResultIntegrityError} When the fetched bytes mismatch the handle.
121
+ * @throws {JobEnvelopeError} When decrypted protocol fields or bindings differ.
122
+ */
123
+ openResult(handle: ResultHandle, options: OpenJobResultOptions): Promise<JobResult>;
124
+ /**
125
+ * Submit, wait for, and decrypt one raw read.
126
+ *
127
+ * @param params - Raw-read request plus polling controls.
128
+ * @returns The decrypted, binding-checked job result.
129
+ * @remarks This convenience flow decrypts the result and therefore requires
130
+ * `builderPrivateKey`; a client configured only with `builderAccount`
131
+ * cannot call `readRaw`.
132
+ * @throws {JobsClientError} When submission, polling, or decryption setup fails.
133
+ * @throws {JobEnvelopeError} When decrypted result bindings differ.
134
+ *
135
+ * @example
136
+ * ```typescript
137
+ * const result = await client.readRaw({
138
+ * owner,
139
+ * grantId,
140
+ * scope: "profile.email",
141
+ * wait: 25,
142
+ * });
143
+ * ```
144
+ */
145
+ readRaw(params: ReadRawParams): Promise<JobResult>;
146
+ }
147
+ /**
148
+ * Create a reusable Node builder client for encrypted Gateway jobs.
149
+ *
150
+ * @param options - Gateway, chain, builder signer, and injectable adapters.
151
+ * @returns A client bound to the configured builder and Gateway.
152
+ * @throws {JobRejectedError} When configuration or signer shape is invalid.
153
+ *
154
+ * @remarks
155
+ * This client is Node-only. `builderPrivateKey` supports the complete flow;
156
+ * `builderAccount` alone supports submit/status/wait but cannot decrypt, so
157
+ * `openResult` and `readRaw` require the raw private key.
158
+ *
159
+ * @example
160
+ * ```typescript
161
+ * const client = createJobsClient({
162
+ * gatewayUrl: "https://gateway.example.com",
163
+ * chainId: 14800,
164
+ * builderPrivateKey: process.env.BUILDER_PRIVATE_KEY as Hex,
165
+ * });
166
+ * const result = await client.readRaw({ owner, grantId, scope: "profile" });
167
+ * ```
168
+ */
169
+ export declare function createJobsClient(options: JobsClientOptions): JobsClient;