feat: Add fetchCandid() function to @dfinity/agent

docs/generated/changelog.html

@@ -18,8 +18,14 @@ <h2>Version 0.13.3</h2>
           the _key non-nullable. This fixes a regression with async window.open behavior in Safari
         </li>
         <li>
-          HttpAgent now offers a method to sync time with the replica, provided a specific canister. 
-          This can be used to set proper Expiry times when a device has fallen out of sync with the replica.
+          HttpAgent now offers a method to sync time with the replica, provided a specific canister.
+          This can be used to set proper Expiry times when a device has fallen out of sync with the
+          replica.
+        </li>
+        <li>
+          Adds a top-level <code>fetchCandid()</code> function which retrieves the Candid interface
+          for a given canister id.
+        </li>
       </ul>
       <h2>Version 0.13.2</h2>
       <ul>

packages/agent/src/fetch_candid.test.ts

@@ -0,0 +1,27 @@
+import { fetchCandid, HttpAgent } from '.';
+import { IDL } from '@dfinity/candid';
+import * as cbor from './cbor';
+
+test('simulate fetching a Candid interface', async () => {
+  const mockFetch = jest.fn().mockImplementationOnce((/*resource, init*/) => {
+    return Promise.resolve(
+      new Response(
+        cbor.encode({
+          status: 'replied',
+          reply: {
+            arg: IDL.encode([IDL.Text], ['service {}']),
+          },
+        }),
+        {
+          status: 200,
+        },
+      ),
+    );
+  });
+
+  const agent = new HttpAgent({ fetch: mockFetch, host: 'http://localhost' });
+
+  const candid = await fetchCandid(agent, 'ryjl3-tyaaa-aaaaa-aaaba-cai');
+
+  expect(candid).toMatch(/service/);
+});

packages/agent/src/fetch_candid.ts

@@ -0,0 +1,21 @@
+import { Actor, ActorSubclass, Agent } from '.';
+import { IDL } from '@dfinity/candid';
+
+// Common interface for the hidden `__get_candid_interface_tmp_hack` actor method
+const tmpHackInterface: IDL.InterfaceFactory = ({ IDL }) =>
+  IDL.Service({
+    __get_candid_interface_tmp_hack: IDL.Func([], [IDL.Text], ['query']),
+  });
+
+/**
+ * Retrieves the Candid interface for the specified canister..
+ *
+ * @param agent The agent to use for the request (usually an `HttpAgent`)
+ * @param canisterId A string corresponding to the canister ID
+ * @returns Candid source code
+ */
+export async function fetchCandid(agent: Agent, canisterId: string): Promise<string> {
+  const actor: ActorSubclass = Actor.createActor(tmpHackInterface, { agent, canisterId });
+  const candidSource = (await actor.__get_candid_interface_tmp_hack()) as string;
+  return candidSource;
+}

packages/agent/src/index.ts

@@ -8,6 +8,7 @@ export * from './agent/http/transforms';
 export * from './agent/http/types';
 export * from './canisters/asset';
 export * from './canisters/management';
+export * from './fetch_candid';
 export * from './request_id';
 export * from './utils/bls';
 export * from './utils/buffer';

packages/candid/tsconfig.json

@@ -18,6 +18,6 @@
     "strict": true,
     "target": "es2017"
   },
-  "include": ["types/*", "src/**/*", "vendor/bls"],
+  "include": ["types/*", "src/**/*", "vendor/bls", "../agent/src/fetch.ts"],
   "references": []
 }