@gofynd/fdk-extension-javascript

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

FDK Extension Helper Library

原始使用文档

fdk-extension-javascript

FDK Extension Helper Library

Initial Setup

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);

How to call platform apis?

To call platform api you need to have instance of PlatformClient. Instance holds methods for SDK classes. All routes registered under platformApiRoutes express router will have platformClient under request object which is instance of PlatformClient.

Here platformApiRoutes has middleware attached which allows passing such request which are called after launching extension under any company.

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);

How to call platform apis in background tasks?

Background tasks running under some consumer or webhook or under any queue can get platform client via method getPlatformClient. It will return instance of PlatformClient as well.

Here FdkClient access_mode should be offline. Cause such client can only access PlatformClient in background task.

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 });
  }
}

How to call partner apis in background tasks?

Background tasks running under some consumer or webhook or under any queue can get partner client via method getPartnerClient. It will return instance of PartnerClient as well.

Here FdkClient access_mode should be offline. Cause such client can only access PartnerClient in background task.

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 });
  }
}

How to call partner apis?

To call partner api you need to have instance of PartnerClient. Instance holds methods for SDK classes. All routes registered under partnerApiRoutes express router will have partnerClient under request object which is instance of PartnerClient.

Here partnerApiRoutes has middleware attached which allows passing such request which are called after launching extension under any company.

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);

How to register for webhook events?

Webhook events can be helpful to handle tasks when certan events occur on platform. You can subscribe to such events by passing webhook_config in setupFdk function.


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`
});

By default all webhook events all subscribed for all companies whenever they are installed. To disable this behavior set subscribe_on_install to false. If subscribe_on_install is set to false, you need to manually enable webhook event subscription by calling syncEvents method of webhookRegistry

There should be view on given api path to receive webhook call. It should be POST api path. Api view should call processWebhook method of webhookRegistry object available under fdkClient here.

Here processWebhook will do payload validation with signature and calls individual handlers for event passed with webhook config.


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});
  }
});

Setting subscribed_saleschannel as "specific" means, you will have to manually subscribe saleschannel level event for individual saleschannel. Default value here is "all" and event will be subscribed for all sales channels. For enabling events manually use function enableSalesChannelWebhook. To disable receiving events for a saleschannel use function disableSalesChannelWebhook.

Filters and reducers in webhook events

A filter and reducer can be provided to refine the data delivered for each subscribed event. The Filter functionality allows selective delivery of data by specifying conditions based on JSONPath queries and logical operators. Reducer allow customization of the payload structure by specifying only the fields needed by the subscriber. The reducer extracts fields from the event’s data and restructures them as needed.

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"
                }
            }]
        }
}
How webhook registery subscribes to webhooks on Fynd Platform?

After webhook config is passed to setupFdk whenever extension is launched to any of companies where extension is installed or to be installed, webhook config data is used to create webhook subscriber on Fynd Platform for that company.

Any update to webhook config will not automatically update subscriber data on Fynd Platform for a company until extension is opened atleast once after the update.

Other way to update webhook config manually for a company is to call syncEvents function of webhookRegistery.

Custom storage class

The FDK Extension JavaScript library provides built-in support for SQLite, Redis and in-memory storage options as default choices for session data storage. However, if you require a different storage option, this readme will guide you through the process of implementing a custom storage class.

版本与发布记录

@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 Extension Helper Library

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