Add fetch permission RPC method (#101)

* Add fetch permission RPC method and public utility

* Apply formatting fixes

* align fetchPermissions

* typecheck

Author: spencerstock

packages/account-sdk/src/core/rpc/coinbase_fetchPermission.ts

@@ -0,0 +1,10 @@
+import { SpendPermission } from './coinbase_fetchSpendPermissions.js';
+
+export type FetchPermissionRequest = {
+  method: 'coinbase_fetchPermission';
+  params: [{ permissionHash: string }];
+};
+
+export type FetchPermissionResponse = {
+  permission: SpendPermission;
+};

packages/account-sdk/src/interface/public-utilities/spend-permission/index.node.ts

@@ -1,4 +1,5 @@
-export * from './methods/fetchPermissions.node.js';
+export * from './methods/fetchPermission.js'; // Same as browser environment.
+export * from './methods/fetchPermissions.js'; // Same as browser environment.
 export * from './methods/getPermissionStatus.node.js';
 export * from './methods/prepareRevokeCallData.js'; // Same as browser environment.
 export * from './methods/prepareSpendCallData.node.js';

packages/account-sdk/src/interface/public-utilities/spend-permission/index.ts

@@ -1,3 +1,4 @@
+export * from './methods/fetchPermission.js';
 export * from './methods/fetchPermissions.js';
 export * from './methods/getHash.js';
 export * from './methods/getPermissionStatus.js';

packages/account-sdk/src/interface/public-utilities/spend-permission/methods/fetchPermission.ts

@@ -0,0 +1,81 @@
+import { CB_WALLET_RPC_URL } from ':core/constants.js';
+import { ProviderInterface } from ':core/provider/interface.js';
+import { FetchPermissionResponse } from ':core/rpc/coinbase_fetchPermission.js';
+import { SpendPermission } from ':core/rpc/coinbase_fetchSpendPermissions.js';
+import { fetchRPCRequest } from ':util/provider.js';
+import { withTelemetry } from '../withTelemetry.js';
+
+type FetchPermissionType = {
+  permissionHash: string;
+  provider?: ProviderInterface;
+};
+
+/**
+ * Fetches a single spend permission by its hash.
+ *
+ * This helper method retrieves a specific spend permission using its unique hash identifier.
+ * This is useful when you have a permission hash and need to retrieve the full permission details.
+ *
+ * The method uses coinbase_fetchPermission RPC method to query the permission
+ * from the backend service. If a provider is supplied, it will use that provider to make the request.
+ * Otherwise, it will make a direct RPC request to the Coinbase Wallet RPC endpoint.
+ *
+ * @param params - The parameters for the fetchPermission method.
+ * @param params.permissionHash - The hash of the permission to fetch.
+ * @param params.provider - Optional provider interface used to make the coinbase_fetchPermission request.
+ *
+ * @returns A promise that resolves to a SpendPermission object.
+ *
+ * @example
+ * ```typescript
+ * import { fetchPermission } from '@base-org/account/spend-permission';
+ *
+ * // Fetch a specific permission by its hash (with provider)
+ * const permission = await fetchPermission({
+ *   provider, // Base Account Provider
+ *   permissionHash: '0x71319cd488f8e4f24687711ec5c95d9e0c1bacbf5c1064942937eba4c7cf2984'
+ * });
+ *
+ * // Fetch a specific permission by its hash (without provider)
+ * const permission = await fetchPermission({
+ *   permissionHash: '0x71319cd488f8e4f24687711ec5c95d9e0c1bacbf5c1064942937eba4c7cf2984'
+ * });
+ *
+ * console.log(`Permission for token: ${permission.permission.token}`);
+ * console.log(`Spender: ${permission.permission.spender}`);
+ * console.log(`Allowance: ${permission.permission.allowance}`);
+ * ```
+ */
+const fetchPermissionFn = async ({
+  provider,
+  permissionHash,
+}: FetchPermissionType): Promise<SpendPermission> => {
+  let response: FetchPermissionResponse;
+
+  if (provider) {
+    response = (await provider.request({
+      method: 'coinbase_fetchPermission',
+      params: [
+        {
+          permissionHash,
+        },
+      ],
+    })) as FetchPermissionResponse;
+  } else {
+    response = (await fetchRPCRequest(
+      {
+        method: 'coinbase_fetchPermission',
+        params: [
+          {
+            permissionHash,
+          },
+        ],
+      },
+      CB_WALLET_RPC_URL
+    )) as FetchPermissionResponse;
+  }
+
+  return response.permission;
+};
+
+export const fetchPermission = withTelemetry(fetchPermissionFn);

packages/account-sdk/src/interface/public-utilities/spend-permission/methods/fetchPermissions.node.test.ts

@@ -1,18 +1,19 @@
 import { CB_WALLET_RPC_URL } from ':core/constants.js';
+import { ProviderInterface } from ':core/provider/interface.js';
 import {
   FetchPermissionsResponse,
   SpendPermission,
 } from ':core/rpc/coinbase_fetchSpendPermissions.js';
 import { fetchRPCRequest } from ':util/provider.js';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { fetchPermissions } from './fetchPermissions.node.js';
+import { fetchPermissions } from './fetchPermissions.js';
 
 // Mock the provider utility
 vi.mock(':util/provider.js');
 
 const mockFetchRPCRequest = vi.mocked(fetchRPCRequest);
 
-describe('fetchPermissions (node)', () => {
+describe('fetchPermissions (without provider)', () => {
   beforeEach(() => {
     vi.clearAllMocks();
   });
@@ -203,3 +204,118 @@ describe('fetchPermissions (node)', () => {
     });
   });
 });
+
+describe('fetchPermissions (with provider)', () => {
+  const mockProvider = {
+    request: vi.fn(),
+  } as unknown as ProviderInterface;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('successful requests', () => {
+    it('should fetch permissions successfully using provider', async () => {
+      const mockPermissions: SpendPermission[] = [
+        {
+          createdAt: 1234567890,
+          permissionHash: '0xabcdef123456',
+          signature: '0x987654321fedcba',
+          chainId: 8453,
+          permission: {
+            account: '0x1234567890abcdef1234567890abcdef12345678',
+            spender: '0x5678901234567890abcdef1234567890abcdef12',
+            token: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
+            allowance: '1000000000000000000',
+            period: 86400,
+            start: 1234567890,
+            end: 1234654290,
+            salt: '123456789',
+            extraData: '0x',
+          },
+        },
+      ];
+
+      const mockResponse: FetchPermissionsResponse = {
+        permissions: mockPermissions,
+      };
+
+      vi.mocked(mockProvider.request).mockResolvedValue(mockResponse);
+
+      const result = await fetchPermissions({
+        provider: mockProvider,
+        account: '0x1234567890abcdef1234567890abcdef12345678',
+        chainId: 8453,
+        spender: '0x5678901234567890abcdef1234567890abcdef12',
+      });
+
+      expect(result).toEqual(mockPermissions);
+      expect(mockProvider.request).toHaveBeenCalledWith({
+        method: 'coinbase_fetchPermissions',
+        params: [
+          {
+            account: '0x1234567890abcdef1234567890abcdef12345678',
+            chainId: '0x2105',
+            spender: '0x5678901234567890abcdef1234567890abcdef12',
+          },
+        ],
+      });
+      // Ensure fetchRPCRequest was NOT called when provider is provided
+      expect(mockFetchRPCRequest).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('parameter handling', () => {
+    it('should convert chainId to hex format correctly with provider', async () => {
+      const mockResponse: FetchPermissionsResponse = {
+        permissions: [],
+      };
+
+      vi.mocked(mockProvider.request).mockResolvedValue(mockResponse);
+
+      const testCases = [
+        { input: 1, expected: '0x1' },
+        { input: 8453, expected: '0x2105' },
+        { input: 137, expected: '0x89' },
+      ];
+
+      for (const testCase of testCases) {
+        vi.mocked(mockProvider.request).mockClear();
+
+        await fetchPermissions({
+          provider: mockProvider,
+          account: '0x1234567890abcdef1234567890abcdef12345678',
+          chainId: testCase.input,
+          spender: '0x5678901234567890abcdef1234567890abcdef12',
+        });
+
+        expect(mockProvider.request).toHaveBeenCalledWith({
+          method: 'coinbase_fetchPermissions',
+          params: [
+            {
+              account: '0x1234567890abcdef1234567890abcdef12345678',
+              chainId: testCase.expected,
+              spender: '0x5678901234567890abcdef1234567890abcdef12',
+            },
+          ],
+        });
+      }
+    });
+  });
+
+  describe('error handling', () => {
+    it('should propagate provider errors', async () => {
+      const errorMessage = 'Provider error';
+      vi.mocked(mockProvider.request).mockRejectedValue(new Error(errorMessage));
+
+      await expect(
+        fetchPermissions({
+          provider: mockProvider,
+          account: '0x1234567890abcdef1234567890abcdef12345678',
+          chainId: 8453,
+          spender: '0x5678901234567890abcdef1234567890abcdef12',
+        })
+      ).rejects.toThrow(errorMessage);
+    });
+  });
+});