feat: fetch subdomain list for bns name (#1132)

* feat: endpoint to fetch subdomains for a name

* fix: resolved docs error

* fix: made requested changes

* style: minor changes

Author: MHassanTariq

docs/api/bns/subdomains/subdomains-list.example.json

@@ -0,0 +1,7 @@
+[
+  "address_test.id.blockstack",
+  "previous_subdomain.id.blockstack",
+  "subdomain.id.blockstack",
+  "zonefile_test.id.blockstack",
+  "zone_test.id.blockstack"
+]

docs/api/bns/subdomains/subdomains-list.schema.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "$id": "subdomains-list-in-name",
+  "title": "GetAllSubdomainsInName",
+  "description": "Fetch a list of subdomains in a name.",
+  "type": "array",
+  "items": {
+    "type": "string",
+    "pattern": "^([a-z0-9-_.+]{3,37})$"
+  }
+}

docs/openapi.yaml

@@ -2536,6 +2536,32 @@ paths:
               example:
                 $ref: ./api/bns/errors/bns-no-such-name.example.json
 
+  /v1/names/{name}/subdomains:
+    get:
+      summary: Get Name Subdomains
+      description: Retrieves the list of subdomains for a specific name
+      tags:
+        - Names
+      operationId: fetch_subdomains_list_for_name
+      parameters:
+        - name: name
+          in: path
+          description: fully-qualified name
+          required: true
+          example: id.blockstack
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: ./api/bns/subdomains/subdomains-list.schema.json
+              example:
+                $ref: ./api/bns/subdomains/subdomains-list.example.json
+        
+
   /v1/names/{name}/zonefile:
     get:
       summary: Get Zone File

src/api/routes/bns/names.ts

@@ -36,6 +36,16 @@ export function createBnsNamesRouter(db: DataStore): express.Router {
     })
   );
 
+  router.get(
+    '/:name/subdomains',
+    asyncHandler(async (req, res, next) => {
+      const { name } = req.params;
+      const includeUnanchored = isUnanchoredRequest(req, res, next);
+      const subdomainsList = await db.getSubdomainsListInName({ name, includeUnanchored });
+      res.json(subdomainsList.results);
+    })
+  );
+
   router.get(
     '/:name/zonefile',
     asyncHandler(async (req, res, next) => {

src/datastore/common.ts

@@ -924,6 +924,14 @@ export interface DataStore extends DataStoreEventEmitter {
   }): Promise<{
     results: string[];
   }>;
+  /**
+   * This function returns the subdomains for a specific name
+   * @param name - The name for which subdomains are required
+   */
+  getSubdomainsListInName(args: {
+    name: string;
+    includeUnanchored: boolean;
+  }): Promise<{ results: string[] }>;
   getSubdomainsList(args: {
     page: number;
     includeUnanchored: boolean;

src/datastore/postgres-store.ts

@@ -6916,6 +6916,30 @@ export class PgDataStore
     return { found: false } as const;
   }
 
+  async getSubdomainsListInName({
+    name,
+    includeUnanchored,
+  }: {
+    name: string;
+    includeUnanchored: boolean;
+  }): Promise<{ results: string[] }> {
+    const queryResult = await this.queryTx(async client => {
+      const maxBlockHeight = await this.getMaxBlockHeight(client, { includeUnanchored });
+      return await client.query<{ fully_qualified_subdomain: string }>(
+        `
+        SELECT DISTINCT ON (fully_qualified_subdomain) fully_qualified_subdomain
+        FROM subdomains
+        WHERE name = $1 AND block_height <= $2
+        AND canonical = true AND microblock_canonical = true
+        ORDER BY fully_qualified_subdomain, block_height DESC, microblock_sequence DESC, tx_index DESC
+        `,
+        [name, maxBlockHeight]
+      );
+    });
+    const results = queryResult.rows.map(r => r.fully_qualified_subdomain);
+    return { results };
+  }
+
   async getSubdomainsList({
     page,
     includeUnanchored,

src/tests-bns/api.ts

@@ -742,6 +742,18 @@ describe('BNS API tests', () => {
     );
   });
 
+  test('Success: subdomains in name', async () => {
+    const query = await supertest(api.server).get(`/v1/names/id.blockstack/subdomains/`);
+    const expectedResult =  [
+      'address_test.id.blockstack',
+      'previous_subdomain.id.blockstack',
+      'subdomain.id.blockstack',
+      'zonefile_test.id.blockstack',
+      'zone_test.id.blockstack'
+    ];
+    expect(query.body).toEqual(expectedResult);
+  });
+
   afterAll(async () => {
     await api.terminate();
     client.release();