@gofynd/fdk-extension-javascript

中文文档
2.0.1发布于 2026/06/24ISCCommonJS构建来源已验证近 30 天下载 3647

FDK 扩展帮助库

中文使用文档

fdk - 扩展- javascript

FDK 扩展帮助库

初始设置

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 附有中间软件,允许在任何公司下发射扩展后发出这种请求.

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.

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.

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 附有中间软件,允许在任何公司下发射扩展后发出这种请求.

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函数中.


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: "[email protected]", // 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配置.


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查询和逻辑操作符指定条件来选择性地提供数据. 缩小器只规定用户需要的字段,从而可以定制有效载荷结构。 减员从事件的数据中提取字段,并根据需要对其进行重组.

webhook_config: {
        api_path: "/v1.0/webhooks",
        notification_email: "[email protected]",
        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 函数.

自定义存储类

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

版本与发布记录

@gofynd/fdk-extension-javascript 共发布 35 个版本,首次发布于 2024/03/05;过去 12 个月发布了 2 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
2.0.1latest2026/06/244 个月前
2.0.02026/04/147 个月前
1.1.5-beta.12025/08/061.3 年前
1.1.52025/08/011.3 年前
1.1.5-beta.02025/07/111.3 年前
1.1.42025/06/101.4 年前

关于 @gofynd/fdk-extension-javascript 的常见问题

@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 和提交记录判断。