@usearete/sdk 0.7.2 → 0.8.0

package/README.md

@@ -75,6 +75,7 @@ Each packaged, attached, or standalone program is canonically available under `s
 - `addresses` - semantic address derivations, when defined
 - `accounts` - typed point reads for program accounts
 - `queries` - program-level HTTP queries
+- `read` - optional program-oriented convenience reads supplied by the SDK
 - `raw` - exact IDL instruction builders with synchronous `.build(...)`
 - `instructions` - semantic one-instruction operations with `.prepare(...)`
 - `transactions` - semantic one-transaction operations with `.prepare(...)`
@@ -96,11 +97,14 @@ const client = await Arete.connect(LOCAL_STACK, {
 });
 ```
 
-Installed hosted SDKs instead contain a complete `hosted-binding` descriptor:
-the release, read endpoint, binding ID, and auth metadata are pinned together.
-Hosted account reads ignore `httpUrl` and stack HTTP endpoints. A
-`programReads` runtime override must replace that complete descriptor; release,
-binding, and endpoint fields are never patched independently.
+Installed hosted program SDKs instead carry a complete `hosted-binding`
+descriptor opaquely inside the exported program cartridge. Passing that one
+program object to `createSession` or `ConnectOptions.programs` automatically
+activates its release-pinned account reads; consumers do not import or register
+the descriptor separately. Hosted account reads ignore `httpUrl` and stack HTTP
+endpoints. The advanced `programReads` override remains available, but it must
+replace the complete descriptor; release, binding, and endpoint fields are never
+patched independently.
 
 Stack and program queries remain stack-HTTP operations. They continue to use
 `httpUrl` or `stack.endpoints.http` and do not use a hosted Program Read binding.

package/dist/index.cjs

@@ -5295,6 +5295,31 @@ function createProgramPdas(pdas) {
     return pdas;
 }
 
+/** Opaque generated-program metadata used to carry its default read transport. */
+const PROGRAM_READ_DESCRIPTOR = Symbol.for('@usearete/sdk/program-read-descriptor');
+/**
+ * Bundle a generated program definition with its default read descriptor.
+ *
+ * Generated SDK entries call this automatically. The descriptor is deliberately
+ * non-enumerable so it remains an implementation detail of the program cartridge.
+ */
+function withProgramRead(program, descriptor) {
+    const properties = Object.getOwnPropertyDescriptors(program);
+    Reflect.deleteProperty(properties, PROGRAM_READ_DESCRIPTOR);
+    const bundled = Object.create(Object.getPrototypeOf(program), properties);
+    Object.defineProperty(bundled, PROGRAM_READ_DESCRIPTOR, {
+        value: descriptor,
+        enumerable: false,
+        configurable: false,
+        writable: false,
+    });
+    return bundled;
+}
+/** Resolve the default read descriptor carried by a generated program SDK. */
+function getProgramReadDescriptor(program) {
+    return program?.[PROGRAM_READ_DESCRIPTOR];
+}
+
 const STACK_RUNTIME_EXTENSIONS = '__areteStackRuntimeExtensions';
 const PROGRAM_OPERATION_EXTENSIONS = '__areteProgramOperationExtensions';
 function defineProgramExtensions() {
@@ -5321,6 +5346,10 @@ function mergeOperations(base, extension) {
 function extendProgram(program, extensions) {
     const base = program;
     const extended = { ...program };
+    const readDescriptor = Object.getOwnPropertyDescriptor(program, PROGRAM_READ_DESCRIPTOR);
+    if (readDescriptor) {
+        Object.defineProperty(extended, PROGRAM_READ_DESCRIPTOR, readDescriptor);
+    }
     delete extended.sdkDefinitionHash;
     for (const key of ['pdas', 'accounts', 'queries', 'addresses', 'constants', 'defaults', 'math']) {
         const extensionValue = extensions[key];
@@ -5333,7 +5362,9 @@ function extendProgram(program, extensions) {
     }
     const baseFactory = base[PROGRAM_OPERATION_EXTENSIONS]?.createOperations;
     const extensionFactory = extensions.createOperations;
-    if (baseFactory || extensionFactory) {
+    const baseReadFactory = base[PROGRAM_OPERATION_EXTENSIONS]?.createRead;
+    const extensionReadFactory = extensions.createRead;
+    if (baseFactory || extensionFactory || baseReadFactory || extensionReadFactory) {
         Object.defineProperty(extended, PROGRAM_OPERATION_EXTENSIONS, {
             value: {
                 createOperations(context) {
@@ -5346,6 +5377,14 @@ function extendProgram(program, extensions) {
                     }
                     return mergeOperations(baseOperations, extensionFactory?.(context));
                 },
+                createRead(context) {
+                    const baseRead = baseReadFactory?.(context);
+                    if (baseRead) {
+                        const connectedProgram = context.program;
+                        connectedProgram.read = mergeNamespace(connectedProgram.read, baseRead);
+                    }
+                    return mergeNamespace(baseRead, extensionReadFactory?.(context));
+                },
             },
             enumerable: false,
             configurable: false,
@@ -6151,7 +6190,9 @@ function createTransactionTransport(baseUrl, authenticatedFetch) {
 }
 
 function effectiveProgramRead(stack, name, override) {
-    return override ?? stack.programReads?.[name];
+    return override
+        ?? stack.programReads?.[name]
+        ?? getProgramReadDescriptor(stack.programs?.[name]);
 }
 function validateReleaseIdentity(programName, definition, release) {
     if (release
@@ -6225,7 +6266,10 @@ function validateProgramReads(stack, overrides, validateDescriptorKeys = true) {
         validateProgramReadDescriptor(key, overrides[key]);
     }
     for (const [name, definition] of Object.entries(stack.programs ?? {})) {
-        validateReleaseIdentity(name, definition, stack.programReads?.[name]?.release);
+        const bundled = getProgramReadDescriptor(definition);
+        if (bundled)
+            validateProgramReadDescriptor(name, bundled);
+        validateReleaseIdentity(name, definition, effectiveProgramRead(stack, name, overrides?.[name])?.release);
         validateReleaseIdentity(name, definition, overrides?.[name]?.release);
     }
 }
@@ -6415,18 +6459,21 @@ let Arete$1 = class Arete {
             const base = bases[name];
             const connectedProgram = {
                 ...base,
+                read: {},
                 instructions: {},
                 transactions: {},
                 flows: {},
             };
             const runtime = getProgramRuntimeExtensions(definition);
-            const operations = runtime?.createOperations({
+            const context = {
                 chain: this._chain,
                 get wallet() {
                     return client._wallet;
                 },
                 program: connectedProgram,
-            });
+            };
+            connectedProgram.read = runtime?.createRead?.(context) ?? {};
+            const operations = runtime?.createOperations?.(context);
             connectedProgram.instructions = operations?.instructions ?? {};
             connectedProgram.transactions = operations?.transactions ?? {};
             connectedProgram.flows = operations?.flows ?? {};
@@ -6866,7 +6913,9 @@ function resolveMemberConnectOptions(stack, member, options, forceHttpOnly) {
 function validateCompositionProgramReads(stack, member, options) {
     const overrides = resolveSessionProgramReads(stack, member, options);
     for (const [name, program] of Object.entries(stack.programs ?? {})) {
-        const descriptor = overrides?.[name] ?? stack.programReads?.[name];
+        const descriptor = overrides?.[name]
+            ?? stack.programReads?.[name]
+            ?? getProgramReadDescriptor(program);
         if (descriptor)
             validateProgramReadDescriptor(name, descriptor);
         if (Object.keys(program.accounts ?? {}).length === 0)
@@ -7464,5 +7513,6 @@ exports.unwrapOperationExecutionError = unwrapOperationExecutionError;
 exports.validateAccountResolution = validateAccountResolution;
 exports.validateProgramReadDescriptor = validateProgramReadDescriptor;
 exports.validateSubscriptionId = validateSubscriptionId;
+exports.withProgramRead = withProgramRead;
 exports.withPrograms = withPrograms;
 //# sourceMappingURL=index.cjs.map