Feature/webhooks-and-developer-managed-signer

Feature/webhooks-and-developer-managed-signer

.gitignore

@@ -9,4 +9,6 @@ build
 # Temporary generated files
 src/neynar-api/neynar-v1-api/openapi-tmp
 src/neynar-api/neynar-v2-api/openapi-farcaster-tmp
-src/neynar-api/neynar-v2-api/openapi-neynar-tmp
+src/neynar-api/neynar-v2-api/openapi-neynar-tmp
+
+test-sdk.ts

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neynar/nodejs-sdk",
-  "version": "1.11.2",
+  "version": "1.12.0",
   "description": "SDK to interact with Neynar APIs (https://docs.neynar.com/)",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",

src/neynar-api/neynar-api-client.ts

@@ -40,6 +40,10 @@ import {
   NeynarFrameCreationRequest,
   UserFIDResponse,
   RegisterUserResponse,
+  DeveloperManagedSigner,
+  WebhookResponse,
+  WebhookSubscriptionFilters,
+  WebhookListResponse,
 } from "./v2/openapi-farcaster";
 
 import {
@@ -798,6 +802,92 @@ export class NeynarAPIClient {
     );
   }
 
+  // ------------ Developer Managed Signer ------------
+
+  /**
+   * Fetches the status of a developer-managed signer by its public key.
+   *
+   * @param {string} publicKey - Ed25519 public key
+   *
+   * @returns {Promise<DeveloperManagedSigner>} A promise that resolves to a `DeveloperManagedSigner` object,
+   *   containing the details and status of the queried signer.
+   *
+   * @example
+   * // Example: Fetch the status of a developer-managed signer by its public key
+   * const publicKey = '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'; // Example public key
+   * client.lookupDeveloperManagedSigner(publicKey).then(response => {
+   *   console.log('Developer Managed Signer Status:', response);
+   * });
+   *
+   * For more information, refer to the [Neynar documentation](https://docs.neynar.com/reference/developer-managed-signer).
+   */
+  public async lookupDeveloperManagedSigner(
+    publicKey: string
+  ): Promise<DeveloperManagedSigner> {
+    return await this.clients.v2.lookupDeveloperManagedSigner(publicKey);
+  }
+
+  /**
+   * Registers an signed key and returns the developer managed signer status with an approval url.
+   *
+   * @param {string} publicKey - Ed25519 public key
+   * @param {string} signature - Signature generated by the custody address of the app. Signed data includes app_fid, deadline, signer’s public key
+   * @param {number} appFid - Application FID
+   * @param {number} deadline - A UNIX timestamp in seconds that controls how long the signed key request is valid for. (24 hours from now is recommended)
+   *
+   * @returns {Promise<DeveloperManagedSigner>} A promise that resolves to a `DeveloperManagedSigner` object.
+   *
+   * @example
+   * // Example: Register a signed key for a developer-managed signer
+   * const publicKey = '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef';
+   * const signature = '0xe5d95c391e165dac8efea373efe301d3ea823e1f41713f8943713cbe2850566672e33ff3e17e19abb89703f650a2597f62b4fda0ce28ca15d59eb6d4e971ee531b';
+   * const appFid = 12345;
+   * const deadline = Math.floor(Date.now() / 1000) + 86400; // 24 hours from now
+   * client.registerSignedKeyForDeveloperManagedSigner(publicKey, signature, appFid, deadline)
+   * .then(response => {
+   *   console.log('Signed Key Registration Response:', response);
+   * });
+   *
+   * For more information, refer to the [Neynar documentation](https://docs.neynar.com/reference/register-signed-key-for-developer-managed-signer).
+   */
+  public async registerSignedKeyForDeveloperManagedSigner(
+    publicKey: string,
+    signature: string,
+    appFid: number,
+    deadline: number
+  ): Promise<DeveloperManagedSigner> {
+    return await this.clients.v2.registerSignedKeyForDeveloperManagedSigner(
+      publicKey,
+      signature,
+      appFid,
+      deadline
+    );
+  }
+
+  /**
+   * Publish a message to farcaster.
+   * The message must be signed by a signer managed by the developer. Use the @farcaster/core library to construct and sign the message.
+   * Use the Message.toJSON method on the signed message and pass the JSON in the body of this POST request.
+   *
+   * @param {object} message - The message object to be published to Farcaster.
+   *
+   * @returns {Promise<object>} A promise that resolves to an `object`.
+   *
+   * @example
+   * // Example: Publish a message to Farcaster
+   * const message = {};
+   * client.publishMessageToFarcaster(message).then(response => {
+   *   console.log('Message Publication Response:', response);
+   * });
+   *
+   * Note: Ensure the message is properly signed using a developer-managed signer before publishing.
+   *
+   * For more information, refer to the [Neynar documentation](https://docs.neynar.com/reference/publish-message).
+   */
+  public async publishMessageToFarcaster(message: object): Promise<object> {
+    return await this.clients.v2.publishMessageToFarcaster(message);
+  }
+
   // ------------ User ------------
 
   /**
@@ -822,7 +912,7 @@ export class NeynarAPIClient {
    * This API is for Enterprise customers only. Please contact us if you want to try this out.
    *
    * Registers a new user account on Farcaster.
-   * 
+   *
    * @param {number} fid - The unique FID assigned to the new user.
    * @param {string} signature - A cryptographic signature proving ownership of the custody address.
    * @param {string} requested_user_custody_address - The Ethereum custody address associated with the new user.
@@ -2144,16 +2234,17 @@ export class NeynarAPIClient {
    *
    * @param {string} messageBytesInHex - The message bytes from the Frame Action in hexadecimal format.
    * @param {Object} [options] - Optional parameters for the validation request.
-   * @param {boolean} [options.castReactionContext] - Include context about cast reactions in the validation response.
-   * @param {boolean} [options.followContext] - Include context about follow actions in the validation response.
+   * @param {boolean} [options.castReactionContext] - Adds viewer_context inside the cast object to indicate whether the interactor reacted to the cast housing the frame.
+   * @param {boolean} [options.followContext] - Adds viewer_context inside the user (interactor) object to indicate whether the interactor follows or is followed by the cast author.
+   * @param {boolean} [options.signerContext] - Adds context about the app used by the user inside `frame.action`.
    *
    * @returns {Promise<ValidateFrameActionResponse>} A promise that resolves to a `ValidateFrameActionResponse` object,
    *   indicating the outcome of the frame action validation, potentially enriched with specified contexts.
    *
    * @example
    * // Example: Validate a frame action with additional context for cast reactions and follow actions
    * const messageBytesInHex = '0a49080d1085940118f6a6a32e20018201390a1a86db69b3ffdf6ab8acb6872b69ccbe7eb6a67af7ab71e95aa69f10021a1908ef011214237025b322fd03a9ddc7ec6c078fb9c56d1a72111214e3d88aeb2d0af356024e0c693f31c11b42c76b721801224043cb2f3fcbfb5dafce110e934b9369267cf3d1aef06f51ce653dc01700fc7b778522eb7873fd60dda4611376200076caf26d40a736d3919ce14e78a684e4d30b280132203a66717c82d728beb3511b05975c6603275c7f6a0600370bf637b9ecd2bd231e';
-   * client.validateFrameAction(messageBytesInHex, { castReactionContext: false, followContext: true }).then(response => {
+   * client.validateFrameAction(messageBytesInHex, { castReactionContext: false, followContext: true, signerContext: true }).then(response => {
    *   console.log('Frame Action Validation:', response);
    * });
    *
@@ -2164,6 +2255,7 @@ export class NeynarAPIClient {
     options?: {
       castReactionContext?: boolean;
       followContext?: boolean;
+      signerContext?: boolean;
     }
   ): Promise<ValidateFrameActionResponse> {
     return await this.clients.v2.validateFrameAction(
@@ -2172,6 +2264,178 @@ export class NeynarAPIClient {
     );
   }
 
+  // ------------ Webhook ------------
+
+  /**
+   * Retrieves details about a specific webhook by its ID.
+   *
+   * @param {string} webhookId - The unique identifier of the webhook to be retrieved.
+   *
+   * @returns {Promise<WebhookResponse>} A promise that resolves to a `WebhookResponse` object,
+   *   containing detailed information about the requested webhook.
+   *
+   * @example
+   * // Example: Fetch information about a specific webhook by ID
+   * const webhookId = 'yourWebhookId';
+   * client.lookupWebhook(webhookId).then(response => {
+   *   console.log('Webhook Details:', response);
+   * });
+   *
+   * For more information, refer to the [Neynar documentation](https://docs.neynar.com/reference/lookup-webhook).
+   */
+  public async lookupWebhook(webhookId: string): Promise<WebhookResponse> {
+    return await this.clients.v2.lookupWebhook(webhookId);
+  }
+
+  /**
+   * Creates a new webhook with the specified parameters. This method enables developers to
+   * programmatically register webhooks for receiving real-time notifications of events that occur
+   * within Farcaster.
+   *
+   * @param {string} name - The name of the webhook.
+   * @param {string} url - The URL to which the webhook events will be sent.
+   * @param {Object} [options] - Optional parameters for the webhook creation.
+   * @param {WebhookSubscriptionFilters} [options.subscription] - A set of filters defining the events the webhook should subscribe to.
+   *
+   * @returns {Promise<WebhookResponse>} A promise that resolves to a `WebhookResponse` object,
+   *   containing information about the newly created webhook, including its ID, name, and subscription details.
+   *
+   * @example
+   * // Example: Create a new webhook for user sign-up events
+   * const name = 'Cast created Webhook';
+   * const url = 'https://example.com/webhook';
+   * const subscription = {
+            "cast.created": {
+                "author_fids": [
+                    3,
+                    196,
+                    194
+                ],
+                "mentioned_fids": [196],
+            },
+            "user.created": {}
+        }
+   * client.publishWebhook(name, url, { subscription }).then(response => {
+   *   console.log('Newly Created Webhook:', response);
+   * });
+   *
+   * For more information, refer to the [Neynar documentation](https://docs.neynar.com/reference/publish-webhook).
+   */
+  public async publishWebhook(
+    name: string,
+    url: string,
+    options?: { subscription: WebhookSubscriptionFilters }
+  ): Promise<WebhookResponse> {
+    return await this.clients.v2.publishWebhook(name, url, options);
+  }
+
+  /**
+   * Updates the active status of a specified webhook.
+   *
+   * @param {string} webhookId - The unique identifier of the webhook whose active status is being toggled.
+   * @param {boolean} active - The desired active status of the webhook. Set to `true` to activate the webhook or `false` to deactivate it.
+   *
+   * @returns {Promise<WebhookResponse>} A promise that resolves to a `WebhookResponse` object.
+   *
+   * @example
+   * // Example: Deactivate a webhook
+   * const webhookId = 'yourWebhookId';
+   * client.updateWebhookActiveStatus(webhookId, false).then(response => {
+   *   console.log('Webhook Active Status Toggled:', response);
+   * });
+   *
+   * // Example: Reactivate a webhook
+   * client.updateWebhookActiveStatus(webhookId, true).then(response => {
+   *   console.log('Webhook Active Status Toggled:', response);
+   * });
+   *
+   * For more information, refer to the [Neynar documentation](https://docs.neynar.com/reference/toggle-webhook-active-status).
+   */
+  public async updateWebhookActiveStatus(
+    webhookId: string,
+    active: boolean
+  ): Promise<WebhookResponse> {
+    return await this.clients.v2.updateWebhookActiveStatus(webhookId, active);
+  }
+
+  /**
+   * Updates an existing webhook with new parameters, including its name, URL, and event subscriptions.
+   *
+   * @param {string} webhookId - The unique identifier of the webhook to be updated.
+   * @param {string} name - The new name for the webhook. Useful for identification and management purposes.
+   * @param {string} url - The new URL to which the webhook events will be sent.
+   * @param {Object} [options] - Optional parameters for updating the webhook.
+   * @param {WebhookSubscriptionFilters} [options.subscription] - A set of filters defining the events the webhook should subscribe to after the update.
+   *
+   * @returns {Promise<WebhookResponse>} A promise that resolves to a `WebhookResponse` object,
+   *   containing the updated information about the webhook, including its ID, name, subscription details, and more.
+   *
+   * @example
+   * // Example: Update an existing webhook with a new URL and subscription filters
+   * const webhookId = 'existingWebhookId';
+   * const newName = 'UpdatedWebhookName';
+   * const newUrl = 'https://example.com/new-webhook-url';
+   * const subscription = {
+            "cast.created": {
+                "author_fids": [
+                    2, 4, 6
+                ],
+                "mentioned_fids": [194],
+            },
+            "user.created": {}
+        }
+   * client.updateWebhook(webhookId, newName, newUrl, { subscription }).then(response => {
+   *   console.log('Updated Webhook:', response);
+   * });
+   *
+   * For more information, refer to the [Neynar documentation](https://docs.neynar.com/reference/update-webhook).
+   */
+  public async updateWebhook(
+    webhookId: string,
+    name: string,
+    url: string,
+    options?: { subscription: WebhookSubscriptionFilters }
+  ): Promise<WebhookResponse> {
+    return await this.clients.v2.updateWebhook(webhookId, name, url, options);
+  }
+
+  /**
+   * Deletes a specified webhook by its unique identifier.
+   *
+   * @param {string} webhookId - The unique identifier of the webhook to be deleted.
+   *
+   * @returns {Promise<WebhookResponse>} A promise that resolves to a `WebhookResponse` object.
+   *
+   * @example
+   * // Example: Delete a specific webhook by ID
+   * const webhookId = 'yourWebhookId';
+   * client.deleteWebhook(webhookId).then(response => {
+   *   console.log('Webhook Deletion Response:', response);
+   * });
+   *
+   * For more information, refer to the [Neynar documentation](https://docs.neynar.com/reference/delete-webhook).
+   */
+  public async deleteWebhook(webhookId: string): Promise<WebhookResponse> {
+    return await this.clients.v2.deleteWebhook(webhookId);
+  }
+
+  /**
+   * Retrieves a list of all webhooks currently associated with the user's account.
+   *
+   * @returns {Promise<WebhookListResponse>} A promise that resolves to a `WebhookListResponse` object.
+   *
+   * @example
+   * // Example: Fetch a list of all webhooks associated with the user's account
+   * client.fetchWebhooks().then(response => {
+   *   console.log('List of Webhooks:', response);
+   * });
+   *
+   * For more information, refer to the [Neynar documentation](https://docs.neynar.com/reference/fetch-webhooks).
+   */
+  public async fetchWebhooks(): Promise<WebhookListResponse> {
+    return await this.clients.v2.fetchWebhooks();
+  }
+
   // ------------ Recommendation ------------
 
   /**