# @gofynd/fdk-extension-javascript 中文文档

规范地址：https://npmcn.com/package/%40gofynd/fdk-extension-javascript/

版本：2\.0\.1
npm 元数据更新时间：2026-06-24T06:08:44.235Z
中文译文更新时间：2026-11-16T18:36:41.654Z
软件包许可：ISC

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40gofynd/fdk-extension-javascript
原文对照：https://npmcn.com/package/%40gofynd/fdk-extension-javascript/?lang=original
项目主页：https://github.com/gofynd/fdk-extension-javascript#readme
源码仓库：https://github.com/gofynd/fdk-extension-javascript

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：143 kB，37 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：9 个
- peer 依赖：@gofynd/fdk-client-javascript \>=3\.4\.2
- 首次发布：2024-03-05T06:45:13.989Z
- 最新版本发布：2026-06-24T06:08:43.459Z
- 近 30 天下载量：3647（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：35（近 12 个月 2 个）

## 中文简介

FDK 扩展帮助库

## 安装

```sh
npm install @gofynd/fdk-extension-javascript
```

也可以使用：`pnpm add @gofynd/fdk-extension-javascript`、`yarn add @gofynd/fdk-extension-javascript`、`bun add @gofynd/fdk-extension-javascript`

## README

# fdk - 扩展- javascript

FDK 扩展帮助库

#### 初始设置

```javascript
const bodyParser = require("body-parser");
const express = require("express");
const cookieParser = require("cookie-parser");
const { setupFdk } = require("fdk-extension-javascript/express");
const { RedisStorage } = require("fdk-extension-javascript/express/storage");
const Redis = require("ioredis");

const app = express();
app.use(cookieParser("ext.session"));
app.use(bodyParser.json({ limit: "2mb" }));

const redis = new Redis();

let extensionHandler = {
  auth: async function (data) {
    console.log("called auth callback");
  },

  uninstall: async function (data) {
    console.log("called uninstall callback");
  },
};

let fdkClient = setupFdk({
  api_key: "<API_KEY>",
  api_secret: "<API_SECRET>",
  base_url: baseUrl, // this is optional
  scopes: ["company/products"], // this is optional
  callbacks: extensionHandler,
  storage: new RedisStorage(redis),
  access_mode: "offline",
});
app.use(fdkClient.fdkHandler);

app.listen(8080);
```

#### 如何唤作平台猿?

要调用平台 API 您需要实例 `PlatformClient`实例为SDK课程提供了方法。 登记的所有路线 `platformApiRoutes` 快速路由器将有 `platformClient` 请求的对象,例如: `PlatformClient`。 。 。 .

> 给 `platformApiRoutes` 附有中间软件,允许在任何公司下发射扩展后发出这种请求.

```javascript
fdkClient.platformApiRoutes.get("/test/routes", async (req, res, next) => {
  try {
    let data = await req.platformClient.lead.getTickets();
    res.json(data);
  } catch (error) {
    console.error(error);
    next(error);
  }
});

app.use(fdkClient.platformApiRoutes);
```

#### 在背景任务中如何调用平台 apis ?

在一些消费者或webhook或任何队列下运行的背景任务可以通过方法获得平台客户端 `getPlatformClient`。它将返回实例 `PlatformClient` 还有.

> 这里 Fdk 客户端 `access_mode` 应该是 **离线**。因为这样的客户端只能在背景任务中访问 PlatfaceClient.

```javascript
function backgroundHandler(companyId) {
  try {
    const platformClient = await fdkExtension.getPlatformClient(companyId);
    let data = await platformClient.lead.getTickets();
    // Some business logic here
    res.json({ success: true });
  } catch (err) {
    console.error(err);
    res.status(404).json({ success: false });
  }
}
```

#### 如何在背景任务中调用伙伴 apis ?

在一些消费者或webhook或任何队列下运行的背景任务可以通过方法获得伙伴客户端 `getPartnerClient`。它将返回实例 `PartnerClient` 还有.

> 这里 Fdk 客户端 `access_mode` 应该是 **离线**。因为这样的客户端只能在背景任务中访问PartnerClient.

```javascript
function backgroundHandler(organizationId) {
  try {
    const partnerClient = await fdkExtension.getPartnerClient(organizationId);
    let data = await partnerClient.webhook.responseTimeSummary({
            extensionId: '<EXTENSION_ID>',
            startDate: '<START_DATE>',
            endDate: '<END_DATE>'
      });
    // Some business logic here
    res.json({ success: true });
  } catch (err) {
    console.error(err);
    res.status(404).json({ success: false });
  }
}
```

#### 如何呼叫伙伴的APIS吗?

要给合伙人打电话,你需要实例 `PartnerClient`实例为SDK课程提供了方法。 登记的所有路线 `partnerApiRoutes` 快速路由器将有 `partnerClient` 请求的对象,例如: `PartnerClient`。 。 。 .

> 给 `partnerApiRoutes` 附有中间软件,允许在任何公司下发射扩展后发出这种请求.

```javascript
fdkClient.partnerApiRoutes.get("/test/routes", async (req, res, next) => {
  try {
    let data = await req.partnerClient.lead.getTickets();
    res.json(data);
  } catch (error) {
    console.error(error);
    next(error);
  }
});

app.use(fdkClient.partnerApiRoutes);
```

#### 如何注册网球赛事?

Webhook事件可以帮助处理在平台上发生的certan事件的任务. 您可以通过途径订阅此类事件 `webhook_config` 在设置Fdk函数中.

```javascript

let fdkClient = setupFdk({
  api_key: "<API_KEY>",
  api_secret: "<API_SECRET>",
  base_url: baseUrl, // this is optional
  scopes: ["company/products"], // this is optional
  callbacks: {
    auth: async function (data) {
      console.log("called auth callback");
    },
    uninstall: async function (data) {
      console.log("called uninstall callback");
    },
  },
  storage: new RedisStorage(redis),
  access_mode: "offline",
  webhook_config: {
    api_path: "/api/v1/webhooks", // required
    notification_email: "test@abc.com", // required
    subscribe_on_install: false, //optional. Default true
    subscribed_saleschannel: 'specific', //optional. Default all
    marketplace: true, // to receive marketplace saleschannel events. Only allowed when subscribed_saleschannel is set to specific
    event_map: { // required
      'company/brand/create': {
        version: '1',
        handler: handleBrandCreate,
        provider: 'rest' // if not provided, Default is `rest`
      },
      'company/location/update': {
        version: '1',
        handler: handleLocationUpdate,
      },
      'application/coupon/create': {
        version: '1',
        topic: 'coupon_create_kafka_topic',
        provider: 'kafka'
      },
      'company/brand/update': {
        version: '1',
        topic: "company-brand-create",  
        provider: 'pub_sub'
      },
      'extension/extension/install': {
        version: '1',
        queue: "extension-install", 
        workflow_name: "extension",
        provider: 'temporal'
      },
      'company/location/create': {
        version: '1',
        queue: "company-location-create",  
        provider: 'sqs'
      },
      'company/product-size/create': {
        version: '1',
        event_bridge_name: "company-product-size-create",  
        provider: 'event_bridge'
      }
    }
  },
  debug: true // optional. Enables debug logs if `true`. Default `false`
});

```

> 默认情况下,所有webhook事件在安装时都会为所有公司订阅. 要禁用此行为集 `subscribe_on_install` 改为 `false`如果 `subscribe_on_install` 设置为虚假, 您需要通过调用来手动启用 webhook 事件订阅 `syncEvents` 方法 `webhookRegistry`

在给定的api路径上应该有视图来接收webhook呼叫. 应该是 `POST` api路径. Api 视图应该调用 `processWebhook` 方法 `webhookRegistry` 可用对象 `fdkClient` 在这里.

> 给 `processWebhook` 将使用签名进行有效载荷验证,并调用个人处理器,以便通过webhook配置.

```javascript

app.post('/api/v1/webhooks', async (req, res, next) => {
  try {
    await fdkClient.webhookRegistry.processWebhook(req);
    return res.status(200).json({"success": true});
  }
  catch(err) {
    logger.error(err);
    return res.status(500).json({"success": false});
  }
});

```

> 设置 `subscribed_saleschannel` 作为"特定"的表示,您必须手动订阅单个销售频道的销售频道级别事件. 这里的默认值是"全部",所有销售渠道都会订阅事件. 用于允许事件手动使用功能 `enableSalesChannelWebhook`。禁用用于销售渠道使用功能的接收事件 `disableSalesChannelWebhook`。 。 。 .

#### 在 Webhook 活动中过滤和缩小

可提供一个过滤器和压缩器,以完善每次订阅活动提供的数据。 Filter功能允许通过根据JSONPath查询和逻辑操作符指定条件来选择性地提供数据. 缩小器只规定用户需要的字段,从而可以定制有效载荷结构。 减员从事件的数据中提取字段,并根据需要对其进行重组.

```javascript
webhook_config: {
        api_path: "/v1.0/webhooks",
        notification_email: "rahultambe@gofynd.com",
        marketplace: true,
        subscribed_saleschannel: 'specific',
        event_map: {
            'company/brand/update': {
                version: '1',
                handler: handleExtensionUninstall,
                filters: {
                    query: "$.brand.uid",
                    condition: "(uid) => uid === 238"
                },
                reducer: {
                    brand_name: "$.brand.name",
                    logo_link: "$.brand.logo"
                }
            }]
        }
}
```

##### Webhook 注册员如何订阅 Fynd 平台上的 Webhoks ?

在Webhook配置被传递给安装或将要安装扩展的任何公司时,每当启动扩展时,Webhook配置数据都会用于在Fynd平台上为该公司创建Webhook用户.

> 对 Webhook 配置的任何更新都不会自动更新一个公司的Fynd平台上的用户数据,直到更新后至少打开一次扩展.

为公司手动更新 Webhook 配置的另一种方式是呼叫 `syncEvents` 函数.

# [自定义存储类](https://npmcn.com/express/storage/README.md)

FDK扩展JavaScript库为SQLite,Redis和in-memory存储选项提供内置支持,作为会话数据存储的默认选择. 然而,如果您需要不同的存储选项,这个readme会引导您执行自定义存储类的过程.

## 常见问题

### @gofynd/fdk-extension-javascript 是什么？

FDK 扩展帮助库

### 如何安装 @gofynd/fdk-extension-javascript？

在项目目录运行 npm install @gofynd/fdk-extension-javascript，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@gofynd/fdk-client-javascript（\>=3\.4\.2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @gofynd/fdk-extension-javascript 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/gofynd\_\_fdk-extension-javascript 是否存在。

### @gofynd/fdk-extension-javascript 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @gofynd/fdk-extension-javascript 可以商用吗？

@gofynd/fdk-extension-javascript 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @gofynd/fdk-extension-javascript 的下载量有多少？

根据 npm 官方下载统计，@gofynd/fdk-extension-javascript 在 2026/10/17 – 2026/11/15 这 30 天内被下载 3,647 次，日均约 122 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @gofynd/fdk-extension-javascript 还在维护吗？

最新版本 2\.0\.1 发布于 2026/06/24（4 个月前）；至今共发布 35 个版本，其中过去 12 个月发布了 2 个；首次发布于 2024/03/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

