feat(twitter): add users.by.username handle->id read cap (#125)

Author: AtelyPham

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-integrations",
-  "version": "0.46.0",
+  "version": "0.47.0",
   "description": "Vendor-neutral integration contracts and runtime helpers for sandbox and agent apps.",
   "homepage": "https://github.com/tangle-network/agent-integrations#readme",
   "repository": {

src/connectors/adapters/twitter.ts

@@ -201,6 +201,23 @@ const TWITTER_SPEC: RestConnectorSpec = {
         query: { max_results: '{max_results}', pagination_token: '{pagination_token}' },
       },
     },
+    {
+      name: 'users.by.username',
+      class: 'read',
+      description:
+        'Resolve a handle to its numeric user id (and name) — for followed_by (resolve target → list users.following) and mentioned-with-target (resolve target → filter users.mentions by author_id). Returns { id, name, username }.',
+      parameters: {
+        type: 'object',
+        properties: {
+          username: {
+            type: 'string',
+            description: 'Twitter/X handle WITHOUT a leading @; resolves to a numeric user id.',
+          },
+        },
+        required: ['username'],
+      },
+      request: { method: 'GET', path: '/users/by/username/{username}' },
+    },
     {
       name: 'users.tweets',
       class: 'read',

tests/twitter.test.ts

@@ -70,14 +70,15 @@ describe('twitter adapter manifest', () => {
     expect(names).toContain('dms.send')
   })
 
-  it('exposes the six quest-verification read capabilities classified as reads', () => {
+  it('exposes the seven quest-verification read capabilities classified as reads', () => {
     const reads = twitterConnector.manifest.capabilities
       .filter((c) => c.class === 'read')
       .map((c) => c.name)
       .sort()
     expect(reads).toEqual([
       'tweets.likingUsers',
       'tweets.retweetedBy',
+      'users.by.username',
       'users.following',
       'users.me',
       'users.mentions',
@@ -165,6 +166,33 @@ describe('twitter read capabilities', () => {
     expect(url.searchParams.get('pagination_token')).toBe('CURSOR')
   })
 
+  it('users.by.username GETs /users/by/username/{username} with no query params', async () => {
+    const captured = captureGet({ data: { id: 'u-7', name: 'Drew', username: 'drew' } })
+    const result = await adapter.executeRead!({
+      source: source(),
+      capabilityName: 'users.by.username',
+      args: { username: 'drew' },
+      idempotencyKey: 'k',
+    })
+    const url = new URL(captured.url)
+    expect(captured.method).toBe('GET')
+    expect(url.origin + url.pathname).toBe('https://api.twitter.com/2/users/by/username/drew')
+    expect([...url.searchParams.keys()]).toEqual([])
+    expect(result.data).toEqual({ data: { id: 'u-7', name: 'Drew', username: 'drew' } })
+  })
+
+  it('users.by.username requires the username', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({})))
+    await expect(
+      adapter.executeRead!({
+        source: source(),
+        capabilityName: 'users.by.username',
+        args: {},
+        idempotencyKey: 'k',
+      }),
+    ).rejects.toThrow(/missing required argument: username/)
+  })
+
   it('users.following requires the user id', async () => {
     vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({})))
     await expect(