add X-Line-Retry-Key support (#224)

* add X-Line-Retry-Key support
* add docs

Author: xingoxu

docs/api-reference/client.md

@@ -11,6 +11,11 @@ class Client {
 
   constructor(config: ClientConfig) {}
 
+  // requestOption
+  setRequestOptionOnce(option: Partial<{
+    retryKey: string;
+  }>)
+
   // Message
   pushMessage(to: string, messages: Message | Message[], notificationDisabled: boolean = false): Promise<MessageAPIResponseBase>
   replyMessage(replyToken: string, messages: Message | Message[], notificationDisabled: boolean = false): Promise<MessageAPIResponseBase>
@@ -152,6 +157,11 @@ interface ClientConfig {
 }
 ```
 
+## Common Specifications
+
+Regarding to things like [Retrying an API request](https://developers.line.biz/en/reference/messaging-api/#retry-api-request), there's an API called `setRequestOptionOnce`. 
+When you call this first and call the API support that request option, then it will be set to that request and will be cleared automatically.
+
 ## Methods
 
 For a parameter `messages: messages: Message | Message[]`, you can provide a

lib/client.ts

@@ -6,6 +6,9 @@ import { AxiosResponse, AxiosRequestConfig } from "axios";
 import { ensureJSON, toArray } from "./utils";
 
 type ChatType = "group" | "room";
+type RequestOption = {
+  retryKey: string;
+};
 import {
   MESSAGING_API_PREFIX,
   DATA_API_PREFIX,
@@ -16,6 +19,8 @@ export default class Client {
   public config: Types.ClientConfig;
   private http: HTTPClient;
 
+  private requestOption: Partial<RequestOption> = {};
+
   constructor(config: Types.ClientConfig) {
     if (!config.channelAccessToken) {
       throw new Error("no channel access token");
@@ -30,6 +35,20 @@ export default class Client {
       ...config.httpConfig,
     });
   }
+  public setRequestOptionOnce(option: Partial<RequestOption>) {
+    this.requestOption = option;
+  }
+
+  private generateRequestConfig(): Partial<AxiosRequestConfig> {
+    const config: Partial<AxiosRequestConfig> = { headers: {} };
+    if (this.requestOption.retryKey) {
+      config.headers["X-Line-Retry-Key"] = this.requestOption.retryKey;
+    }
+
+    // clear requestOption
+    this.requestOption = {};
+    return config;
+  }
 
   private parseHTTPResponse(response: AxiosResponse) {
     const { LINE_REQUEST_ID_HTTP_HEADER_NAME } = Types;
@@ -48,11 +67,15 @@ export default class Client {
     messages: Types.Message | Types.Message[],
     notificationDisabled: boolean = false,
   ): Promise<Types.MessageAPIResponseBase> {
-    return this.http.post(`${MESSAGING_API_PREFIX}/message/push`, {
-      messages: toArray(messages),
-      to,
-      notificationDisabled,
-    });
+    return this.http.post(
+      `${MESSAGING_API_PREFIX}/message/push`,
+      {
+        messages: toArray(messages),
+        to,
+        notificationDisabled,
+      },
+      this.generateRequestConfig(),
+    );
   }
 
   public replyMessage(
@@ -72,11 +95,15 @@ export default class Client {
     messages: Types.Message | Types.Message[],
     notificationDisabled: boolean = false,
   ): Promise<Types.MessageAPIResponseBase> {
-    return this.http.post(`${MESSAGING_API_PREFIX}/message/multicast`, {
-      messages: toArray(messages),
-      to,
-      notificationDisabled,
-    });
+    return this.http.post(
+      `${MESSAGING_API_PREFIX}/message/multicast`,
+      {
+        messages: toArray(messages),
+        to,
+        notificationDisabled,
+      },
+      this.generateRequestConfig(),
+    );
   }
 
   public async narrowcast(
@@ -86,23 +113,31 @@ export default class Client {
     limit?: { max: number },
     notificationDisabled: boolean = false,
   ): Promise<Types.MessageAPIResponseBase> {
-    return this.http.post(`${MESSAGING_API_PREFIX}/message/narrowcast`, {
-      messages: toArray(messages),
-      recipient,
-      filter,
-      limit,
-      notificationDisabled,
-    });
+    return this.http.post(
+      `${MESSAGING_API_PREFIX}/message/narrowcast`,
+      {
+        messages: toArray(messages),
+        recipient,
+        filter,
+        limit,
+        notificationDisabled,
+      },
+      this.generateRequestConfig(),
+    );
   }
 
   public async broadcast(
     messages: Types.Message | Types.Message[],
     notificationDisabled: boolean = false,
   ): Promise<Types.MessageAPIResponseBase> {
-    return this.http.post(`${MESSAGING_API_PREFIX}/message/broadcast`, {
-      messages: toArray(messages),
-      notificationDisabled,
-    });
+    return this.http.post(
+      `${MESSAGING_API_PREFIX}/message/broadcast`,
+      {
+        messages: toArray(messages),
+        notificationDisabled,
+      },
+      this.generateRequestConfig(),
+    );
   }
 
   public async getProfile(userId: string): Promise<Types.Profile> {

lib/http.ts

@@ -50,9 +50,17 @@ export default class HTTPClient {
     return res.data as Readable;
   }
 
-  public async post<T>(url: string, body?: any): Promise<T> {
+  public async post<T>(
+    url: string,
+    body?: any,
+    config?: Partial<AxiosRequestConfig>,
+  ): Promise<T> {
     const res = await this.instance.post(url, body, {
-      headers: { "Content-Type": "application/json" },
+      headers: {
+        "Content-Type": "application/json",
+        ...(config && config.headers),
+      },
+      ...config,
     });
 
     return this.responseParse(res);
@@ -70,7 +78,10 @@ export default class HTTPClient {
     config?: Partial<AxiosRequestConfig>,
   ): Promise<T> {
     const res = await this.instance.put(url, body, {
-      headers: { "Content-Type": "application/json" },
+      headers: {
+        "Content-Type": "application/json",
+        ...(config && config.headers),
+      },
       ...config,
     });
 

test/client.spec.ts

@@ -807,6 +807,45 @@ describe("client", () => {
     equal(scope.isDone(), true);
   });
 
+  it("set option once and clear option", async () => {
+    const expectedBody = {
+      messages: [testMsg],
+      to: "test_user_id",
+      notificationDisabled: false,
+    };
+    const retryKey = "retryKey";
+
+    const firstRequest = nock(MESSAGING_API_PREFIX, {
+      reqheaders: {
+        ...interceptionOption.reqheaders,
+        "X-Line-Retry-Key": retryKey,
+      },
+    })
+      .post(`/message/push`, expectedBody)
+      .reply(responseFn);
+    const secondRequest = mockPost(MESSAGING_API_PREFIX, `/message/push`, {
+      messages: [testMsg],
+      to: "test_user_id",
+      notificationDisabled: false,
+    });
+
+    client.setRequestOptionOnce({
+      retryKey,
+    });
+
+    const firstResPromise = client.pushMessage("test_user_id", testMsg);
+    const secondResPromise = client.pushMessage("test_user_id", testMsg);
+
+    const [firstRes, secondRes] = await Promise.all([
+      firstResPromise,
+      secondResPromise,
+    ]);
+    equal(firstRequest.isDone(), true);
+    equal(secondRequest.isDone(), true);
+    equal(firstRes["x-line-request-id"], "X-Line-Request-Id");
+    equal(secondRes["x-line-request-id"], "X-Line-Request-Id");
+  });
+
   it("fails on construct with no channelAccessToken", () => {
     try {
       new Client({ channelAccessToken: null });