Merge pull request #31 from line/export-types

Export exceptions and types from top-level import

Author: Hyunje Jun

.travis.yml

@@ -1,5 +1,5 @@
 language: node_js
 node_js:
+  - "4"
   - "6"
-  - "7"
   - "8"

CONTRIBUTING.md

@@ -1,8 +1,8 @@
 # How to contribute to LINE Bot SDK for Node.js
 
 First of all, thank you so much for taking your time to contribute! LINE Bot SDK
-for Node.js is not very different from any other open source projects you are
-aware of. It will be amazing if you could help us by doing any of the following:
+for Node.js is not very different from any other open source projects. It will
+be fantastic if you help us by doing any of the following:
 
 - File an issue in [the issue tracker](https://github.com/line/line-bot-sdk-nodejs/issues)
   to report bugs and propose new features and improvements.
@@ -17,7 +17,6 @@ Here are each top-level directory explained:
 
 * `lib`: TypeScript source code. You may modify files under this directory.
 * `test`: Mocha test suites. Please add tests for modification if possible.
-* `types`: Project-level type declarations
 * `examples`: Example projects using this SDK
 * `docs`: [GitBook](https://www.gitbook.com/) markdowns for project documentation
 * `tools`: Useful tools

docs/SUMMARY.md

@@ -13,5 +13,6 @@
   * [validateSignature](pages/api-reference/validate-signature.md)
   * [middleware](pages/api-reference/middleware.md)
   * [Exceptions](pages/api-reference/exceptions.md)
+  * [Message and event objects](pages/api-reference/message-and-event-objects.md)
 * [Contributing](CONTRIBUTING.md)
 * [GitHub](https://github.com/line/line-bot-sdk-nodejs/)

docs/pages/api-reference.md

@@ -1,6 +1,6 @@
 # API Reference
 
-When imported via `require` or `import`, 3 interfaces are exposed.
+Please import the library via `require` or `import`.
 
 ``` js
 // CommonJS
@@ -15,15 +15,5 @@ For the detailed API reference of each, please refer to their own pages.
 - [Client](api-reference/client.md)
 - [validateSignature](api-reference/validate-signature.md)
 - [middleware](api-reference/middleware.md)
-
-Exceptions can be imported via `@line/bot-sdk/exceptions`.
-
-``` js
-// CommonJS
-const JSONParseError = require('@line/bot-sdk/exceptions').JSONParseError;
-
-// ES2015 modules or TypeScript
-import { JSONParseError } from '@line/bot-sdk/exceptions';
-```
-
 - [Exceptions](api-reference/exceptions.md)
+- [Message and event objects](api-reference/message-and-event-objects.md)

docs/pages/api-reference/client.md

@@ -26,15 +26,16 @@ class Client {
 ```
 
 `Message` is a valid message object. About message object structure, please
-refer to [Send message object](https://developers.line.me/en/docs/messaging-api/reference/#message-objects)
-of the official documentation.
+refer to [Message and event objects](./message-and-event-objects.md) on this guide, or
+[Send message object](https://developers.line.me/en/docs/messaging-api/reference/#message-objects)
+on the official documentation.
 
-`ClientConfig` type is like below, except that it also allows fields
-from [MiddlewareConfig](./middleware.md) too.
+`ClientConfig` type is like below.
 
 ``` typescript
-type ClientConfig = {
-  channelAccessToken: string,
+interface ClientConfig {
+  channelAccessToken: string;
+  channelSecret?: string;
 }
 ```
 

docs/pages/api-reference/exceptions.md

@@ -1,14 +1,14 @@
 # Exceptions
 
-Exception classes can be imported via `@line/bot-sdk/exceptions'`.
+Exception classes can also be imported from `@line/bot-sdk`.
 
 ``` js
-// CommonJS
-const HTTPError = require('@line/bot-sdk/exceptions').HTTPError;
-const JSONParseError = require('@line/bot-sdk/exceptions').JSONParseError;
-const ReadError = require('@line/bot-sdk/exceptions').ReadError;
-const RequestError = require('@line/bot-sdk/exceptions').RequestError;
-const SignatureValidationFailed = require('@line/bot-sdk/exceptions').SignatureValidationFailed;
+// CommonJS (destructuring can be used for Node.js >= 6)
+const HTTPError = require('@line/bot-sdk').HTTPError;
+const JSONParseError = require('@line/bot-sdk').JSONParseError;
+const ReadError = require('@line/bot-sdk').ReadError;
+const RequestError = require('@line/bot-sdk').RequestError;
+const SignatureValidationFailed = require('@line/bot-sdk').SignatureValidationFailed;
 
 // ES2015 modules or TypeScript
 import {

docs/pages/api-reference/message-and-event-objects.md

@@ -0,0 +1,31 @@
+# Message and event objects
+
+The message objects and event objects are plain JS objects with no
+abstraction. This SDK provides TypeScript types for them, which can be imported
+from `@line/bot-sdk`.
+
+Please beware that the types only work in TypeScript, and will be removed when
+built into JavaScript.
+
+``` typescript
+import {
+  // webhook event objects
+  WebhookEvent,
+  MessageEvent,
+  EventSource,
+  VideoEventMessage,
+
+  // message event objects
+  Message,
+  TemplateMessage,
+  TemplateContent,
+} from "@line/bot-sdk";
+```
+
+For the actual type definitions, please refer to [types.ts](https://github.com/line/line-bot-sdk-nodejs/blob/master/lib/types.ts)
+directly.
+
+You can also refer to the official specification:
+
+- [Message objects](https://developers.line.me/en/docs/messaging-api/reference/#message-objects)
+- [Webhook event objects](https://developers.line.me/en/docs/messaging-api/reference/#webhook-event-objects)

docs/pages/api-reference/middleware.md

@@ -9,12 +9,12 @@ by several Node.js web frameworks such as [Express](https://expressjs.com/).
 function middleware(config: MiddlewareConfig): Middleware
 ```
 
-The types of `MiddlewareConfig` and `Middleware` are like below, except that the config allows
-fields from [ClientConfig](./client.md) too.
+The types of `MiddlewareConfig` and `Middleware` are like below.
 
 ``` typescript
-type MiddlewareConfig = {
-  channelSecret: string,
+interface MiddlewareConfig {
+  channelAccessToken?: string;
+  channelSecret: string;
 }
 
 type Middleware =

docs/pages/guide/typescript.md

@@ -26,7 +26,7 @@ Also, when building a complex message object, you can make use of types for
 its fields.
 
 ``` typescript
-const message: Line.TemplateMessage = {
+const message: TemplateMessage = {
   type: "template",
   altText: "cannot display template message",
   template: {
@@ -45,7 +45,7 @@ const message: Line.TemplateMessage = {
 ```
 
 The object above will be type-checked to have the type of
-`Line.TemplateMessage`, and thus ensured not to miss any required field.
+`TemplateMessage`, and thus ensured not to miss any required field.
 
 Also, [literal type](https://www.typescriptlang.org/docs/handbook/advanced-types.html)
 is used for `type` fields, which means the compiler will complain if a wrong
@@ -57,9 +57,21 @@ The library is built to just-work with TypeScript too, so import the library and
 there you go.
 
 ``` typescript
-import { Client, validateSignature, middleware } from "@line/bot-sdk";
+import {
+  // main APIs
+  Client,
+  middleware,
+
+  // exceptions
+  JSONParseError,
+  SignatureValidationFailed,
+
+  // types
+  TemplateMessage,
+  WebhookEvent,
+} from "@line/bot-sdk";
 ```
 
-Webhook event and message object types are defined in the `Line` namespace, e.g.
-`Line.WebhookEvent` or `Line.Message`. For declarations of the types, please
-refer to [global.d.ts](https://github.com/line/line-bot-sdk-nodejs/blob/master/types/global.d.ts).
+Message object and webhook event types can be also imported from `@line/bot-sdk`,
+e.g. `TemplateMessage` or `WebhookEvent`. For declarations of the types, please
+refer to [types.ts](https://github.com/line/line-bot-sdk-nodejs/blob/master/lib/types.ts).

docs/pages/guide/webhook.md

@@ -20,7 +20,8 @@ function to do this.
 
 **Webhook event object parsing** is literally parsing webhook event objects,
 which contains information of each webhook event. The objects are provided as
-request body in JSON format, so any body parser will work here.
+request body in JSON format, so any body parser will work here. For interal
+object types in this SDK, please refer to [Message and event objects](../api-reference/message-and-event-objects.md).
 
 There is a function to generate a [connect](https://github.com/senchalabs/connect) middleware,
 [`middleware()`](../api-reference/middleware.md), to conduct both of them. If
@@ -131,8 +132,8 @@ The errors can be handled with [error middleware](https://github.com/senchalabs/
 ``` js
 const express = require('express')
 const middleware = require('@line/bot-sdk').middleware
-const JSONParseError = require('@line/bot-sdk/exceptions').JSONParseError
-const SignatureValidationFailed = require('@line/bot-sdk/exceptions').SignatureValidationFailed
+const JSONParseError = require('@line/bot-sdk').JSONParseError
+const SignatureValidationFailed = require('@line/bot-sdk').SignatureValidationFailed
 
 const app = express()
 

exceptions.js

@@ -1,11 +1,12 @@
 import { get, post, stream } from "./http";
+import * as Types from "./types";
 import * as URL from "./urls";
 import { toArray } from "./util";
 
 export default class Client {
-  public config: Line.ClientConfig;
+  public config: Types.ClientConfig;
 
-  constructor(config: Line.Config & Line.ClientConfig) {
+  constructor(config: Types.ClientConfig) {
     if (!config.channelAccessToken) {
       throw new Error("no channel access token");
     }
@@ -15,7 +16,7 @@ export default class Client {
 
   public pushMessage(
     to: string,
-    messages: Line.Message | Line.Message[],
+    messages: Types.Message | Types.Message[],
   ): Promise<any> {
     return this.post(URL.push, {
       messages: toArray(messages),
@@ -25,7 +26,7 @@ export default class Client {
 
   public replyMessage(
     replyToken: string,
-    messages: Line.Message | Line.Message[],
+    messages: Types.Message | Types.Message[],
   ): Promise<any> {
     return this.post(URL.reply, {
       messages: toArray(messages),
@@ -35,29 +36,29 @@ export default class Client {
 
   public multicast(
     to: string[],
-    messages: Line.Message | Line.Message[],
+    messages: Types.Message | Types.Message[],
   ): Promise<any> {
     return this.post(URL.multicast, {
       messages: toArray(messages),
       to,
     });
   }
 
-  public getProfile(userId: string): Promise<Line.Profile> {
+  public getProfile(userId: string): Promise<Types.Profile> {
     return this.get(URL.profile(userId));
   }
 
   public getGroupMemberProfile(
     groupId: string,
     userId: string,
-  ): Promise<Line.Profile> {
+  ): Promise<Types.Profile> {
     return this.get(URL.groupMemberProfile(groupId, userId));
   }
 
   public getRoomMemberProfile(
     roomId: string,
     userId: string,
-  ): Promise<Line.Profile> {
+  ): Promise<Types.Profile> {
     return this.get(URL.roomMemberProfile(roomId, userId));
   }
 

exceptions.ts

@@ -3,3 +3,7 @@ import middleware from "./middleware";
 import validateSignature from "./validate-signature";
 
 export { Client, middleware, validateSignature };
+
+// re-export exceptions and types
+export * from "./exceptions";
+export * from "./types";

lib/client.ts

@@ -1,6 +1,7 @@
 import { raw } from "body-parser";
 import * as http from "http";
 import { JSONParseError, SignatureValidationFailed } from "./exceptions";
+import * as Types from "./types";
 import validateSignature from "./validate-signature";
 
 export type Request = http.IncomingMessage & { body: any };
@@ -13,9 +14,7 @@ export type Middleware = (
   next: NextCallback,
 ) => void;
 
-export default function middleware(
-  config: Line.Config & Line.MiddlewareConfig,
-): Middleware {
+export default function middleware(config: Types.MiddlewareConfig): Middleware {
   if (!config.channelSecret) {
     throw new Error("no channel secret");
   }