chore: add TypeScript typings file

index.d.ts

@@ -2,40 +2,57 @@
 
 import { IncomingMessage, ServerResponse } from 'http';
 
-export declare const agent: Agent;
+export default agent;
 
-declare class Agent {
-  middleware: { connect: ConnectMiddlewareFn };
-  lambda: LambdaFn;
-  // logger: Logger // TODO: Is this an official API?
-
-  currentSpan: Span | null;
-  currentTransaction: Transaction | null;
+declare const agent: Agent;
 
+declare class Agent {
+  // Configuration
   start (options: AgentConfigOptions): Agent;
   isStarted (): boolean;
 
-  addFilter (fn: FilterFn): void;
-  addErrorFilter (fn: FilterFn): void;
-  addSpanFilter (fn: FilterFn): void;
-  addTransactionFilter (fn: FilterFn): void;
+  // Data collection hooks
+  middleware: { connect(): ConnectMiddlewareFn };
+  lambda: LambdaFn;
   handleUncaughtExceptions (fn: UncaughtExceptionFn): void;
 
-  captureError (err: Error | string | ParameterizedMessageObject, options?: CaptureErrorOptions, callback?: CaptureErrorCallback): void;
-
+  // Errors
+  captureError (
+    err: Error | string | ParameterizedMessageObject,
+    callback?: CaptureErrorCallback
+  ): void;
+  captureError (
+    err: Error | string | ParameterizedMessageObject,
+    options?: CaptureErrorOptions,
+    callback?: CaptureErrorCallback
+  ): void;
+
+  // Transactions
   startTransaction (name?: string, type?: string, options?: TransactionOptions): Transaction | null;
   setTransactionName (name: string): void;
   endTransaction: EndTransactionFn;
-
+  currentTransaction: Transaction | null;
+
+  // Spans
   startSpan: StartSpanFn;
+  currentSpan: Span | null;
 
+  // Context
   setTag: SetTagFn; // TODO: Is this how to add a declared function to a class?
   addTags: AddTagsFn;
   setUserContext (user: UserObject): void;
   setCustomContext (custom: object): void;
 
+  // Transport
+  addFilter (fn: FilterFn): void;
+  addErrorFilter (fn: FilterFn): void;
+  addSpanFilter (fn: FilterFn): void;
+  addTransactionFilter (fn: FilterFn): void;
   flush (callback: Function): void;
   destroy (): void;
+
+  // Utils
+  logger: Logger; // TODO: Should we advertise this API?
 }
 
 declare class GenericSpan {
@@ -93,7 +110,7 @@ interface AgentConfigOptions {
   logLevel?: LogLevel;
   logger?: Logger;
   metricsInterval?: string | number; // TODO: Do we officially want to support numbers?
-  payloadLogFile?: string; // TODO: Do we want to advertise this?
+  payloadLogFile?: string; // TODO: Should we advertise this API?
   secretToken?: string;
   serverTimeout?: string | number; // TODO: Do we officially want to support numbers?
   serverUrl?: string;
@@ -115,24 +132,24 @@ interface CaptureErrorOptions {
   timestamp?: number;
   handled?: boolean; // TODO: Currently not documented - should we expose this?
   user?: UserObject;  
-  tags?: Tags; // TODO: currently not documented
+  tags?: Tags; // TODO: Currently not documented
   custom?: object;
   message?: string;
 }
 
 interface Tags {
-  [key: string]: any; // TODO: Can't we specify it a bit more than any?
+  [key: string]: TagValue;
 }
 
 interface UserObject {
-  id?: any; // TODO: Only string?
-  username?: string;
-  email?: string;
+  id?: string | number | null | undefined;
+  username?: string | null | undefined;
+  email?: string | null | undefined;
 }
 
 interface ParameterizedMessageObject {
   message: string;
-  params: Array<any>; // TODO: Can we narrow it down a bit more any
+  params: Array<any>;
 }
 
 interface Logger {
@@ -159,7 +176,7 @@ interface SpanOptions {
   childOf?: Transaction | Span | string // TODO: This technically accepts other values, but we might not want to document these?
 }
 
-type SetTagFn = (name: string, value: any) => boolean;
+type SetTagFn = (name: string, value: TagValue) => boolean;
 type AddTagsFn = (tags: Tags) => boolean;
 type StartSpanFn = (name?: string, type?: string, options?: SpanOptions) => Span | null;
 type EndTransactionFn = (result?: string | null, endTime?: number) => void; // TODO: Should we allow number as well for result?
@@ -168,13 +185,13 @@ type UncaughtExceptionFn = (err: Error) => void;
 
 type CaptureErrorCallback = (err: Error | null, id: string) => void;
 
-type FilterFn = (payload: object) => object | Falsy;
+type FilterFn = (payload: object) => object | Falsy | void;
 
 type LambdaFn =
   | ((handler: LambdaHandlerFn) => LambdaHandlerFn)
   | ((type: string, handler: LambdaHandlerFn) => LambdaHandlerFn);
-type LambdaHandlerFn = (event: object, context: object, callback: LambdaHandlerCallbackFn) => any;
-type LambdaHandlerCallbackFn = (err?: Error | null | undefined, result?: any) => void;
+type LambdaHandlerFn = (event: object, context: object, callback: LambdaHandlerCallbackFn) => any; // TODO: Is the `any` return type correct?
+type LambdaHandlerCallbackFn = (err?: Error | null | undefined, result?: any) => void; // TODO: Can `result` really be `any`?
 
 type ConnectMiddlewareFn = (err: Error, req: IncomingMessage, res: ServerResponse, next: ConnectMiddlewareNextFn) => void;
 type ConnectMiddlewareNextFn = (err?: Error) => void;
@@ -183,4 +200,5 @@ type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
 type CaptureErrorLogStackTraces = 'never' | 'messages' | 'always';
 type CaptureBody = 'off' | 'errors' | 'transactions' | 'all';
 
-type Falsy = false | 0 | "" | null | undefined // Not possible to define NaN
+type TagValue = string | number | boolean | null | undefined;
+type Falsy = false | 0 | "" | null | undefined; // Not possible to define NaN

start.d.ts

@@ -1,2 +1,2 @@
-import * as agent from './';
-export = agent;
+import agent from './';
+export default agent;