Expose AJS types and update README (#173)

* Expose AJS types

* improve types

* add info on how to use types from npm

Author: Julio Farah

README.md

@@ -7,6 +7,16 @@ This is the core of [Analytics.js][], the open-source library that powers data c
 
 To build this into a full, usable library, see the [Analytics.js](https://github.com/segmentio/analytics.js) repository.
 
+## Using Types
+
+We've recently introduced Typescript support and types to Analytics.js Core. While the exposed types still need some work
+(pull requests are welcome!), they're ready to be used.
+
+### Importing as an npm module
+
+If you use analytics.js-core as an npm module, you can leverage its types out of the box:
+<img src="![types](https://user-images.githubusercontent.com/484013/88733944-bbcf3680-d0ec-11ea-904c-a63b68f4975e.gif)" alt="Example of using analytics js types" width="500px">
+
 ## License
 
 Released under the [MIT license](LICENSE).

lib/analytics.ts

@@ -134,7 +134,6 @@ Analytics.prototype.addIntegrationMiddleware = function(
  * Destination Middleware is chained after integration middleware
  */
 
-// TODO remove `unknown`
 Analytics.prototype.addDestinationMiddleware = function(
   integrationName: string,
   middlewares: Array<unknown>
@@ -339,7 +338,7 @@ Analytics.prototype.identify = function(
  * @return {Object}
  */
 
-Analytics.prototype.user = function() {
+Analytics.prototype.user = function(): object {
   return user;
 };
 
@@ -399,7 +398,7 @@ Analytics.prototype.group = function(
  */
 
 Analytics.prototype.track = function(
-  event: number,
+  event: string,
   properties: unknown,
   options: unknown,
   fn: unknown
@@ -517,7 +516,7 @@ Analytics.prototype.trackClick = Analytics.prototype.trackLink = function(
 Analytics.prototype.trackSubmit = Analytics.prototype.trackForm = function(
   forms: Element | Array<unknown>,
   event: any,
-  properties: any
+  properties?: any
 ): SegmentAnalytics {
   if (!forms) return this;
   // always arrays, handles jquery
@@ -646,9 +645,9 @@ Analytics.prototype.pageview = function(url: string): SegmentAnalytics {
 
 Analytics.prototype.alias = function(
   to: string,
-  from: string,
-  options: unknown,
-  fn: unknown
+  from?: string,
+  options?: unknown,
+  fn?: unknown
 ): SegmentAnalytics {
   // Argument reshuffling.
   /* eslint-disable no-unused-expressions, no-sequences */
@@ -960,7 +959,7 @@ Analytics.prototype._parseQuery = function(query: string): SegmentAnalytics {
 
 Analytics.prototype.normalize = function(msg: {
   context: { page };
-  anonymousId;
+  anonymousId: string;
 }): object {
   msg = normalize(msg, keys(this._integrations));
   if (msg.anonymousId) user.anonymousId(msg.anonymousId);
@@ -1012,7 +1011,7 @@ Analytics.prototype._mergeInitializeAndPlanIntegrations = function(
  * No conflict support.
  */
 
-Analytics.prototype.noConflict = function() {
+Analytics.prototype.noConflict = function(): SegmentAnalytics {
   window.analytics = _analytics;
   return this;
 };

lib/global-modules.d.ts

@@ -1,8 +1,16 @@
-export {};
+import { SegmentAnalytics } from './index.d'
 
 declare global {
+  namespace NodeJS {
+    interface Global {
+      analytics: SegmentAnalytics.AnalyticsJS
+    }
+  }
   interface Window {
+    analytics: SegmentAnalytics.AnalyticsJS
     jQuery: any;
     Zepto: any;
   }
 }
+
+export {};

lib/global.d.ts

@@ -0,0 +1,277 @@
+export namespace SegmentAnalytics {
+  export interface SegmentOpts {
+    integrations?: any;
+    anonymousId?: string;
+    context?: object;
+  }
+
+  export interface IntegrationsSettings {
+    // TODO remove `any`
+    [key: string]: any;
+  }
+
+  export interface CookieOptions {
+    maxage?: number;
+    domain?: string;
+    path?: string;
+    secure?: boolean;
+  }
+
+  export interface MetricsOptions {
+    host?: string;
+    sampleRate?: number;
+    flushTimer?: number;
+    maxQueueSize?: number;
+  }
+
+  export interface StoreOptions {
+    enabled?: boolean;
+  }
+
+  export interface UserOptions {
+    cookie?: {
+      key: string;
+      oldKey: string;
+    };
+    localStorage?: {
+      key: string;
+    };
+    persist?: boolean;
+  }
+
+  export interface GroupOptions {
+    cookie?: {
+      key: string;
+    };
+    localStorage?: {
+      key: string;
+    };
+    persist?: boolean;
+  }
+
+  export interface SegmentIntegration {
+    All?: boolean;
+    [integration: string]: boolean | undefined;
+  }
+
+  export interface InitOptions {
+    initialPageview?: boolean;
+    cookie?: CookieOptions;
+    metrics?: MetricsOptions;
+    localStorage?: StoreOptions;
+    user?: UserOptions;
+    group?: GroupOptions;
+    integrations?: SegmentIntegration;
+  }
+
+  export interface AnalyticsJS {
+    Integrations: { [name: string]: unknown };
+    require: any;
+    VERSION: any;
+
+    /**
+     * Use a `plugin`.
+     */
+    use(plugin: (analytics: AnalyticsJS) => void): AnalyticsJS;
+
+    /**
+     * Define a new `Integration`.
+     */
+    addIntegration(Integration: (options: SegmentOpts) => void): AnalyticsJS;
+
+    /**
+     * Define a new `SourceMiddleware`
+     */
+    addSourceMiddleware(middleware: Function): AnalyticsJS;
+
+    /**
+     * Define a new `IntegrationMiddleware`
+     * @deprecated Use addDestinationMiddleware instead
+     */
+    addIntegrationMiddleware(middleware: Function): AnalyticsJS;
+
+    /**
+     * Define a new `DestinationMiddleware`
+     * Destination Middleware is chained after integration middleware
+     */
+    addDestinationMiddleware(
+      integrationName: string,
+      middlewares: Array<unknown>
+    ): AnalyticsJS;
+
+    /**
+     * Initialize with the given integration `settings` and `options`.
+     *
+     * Aliased to `init` for convenience.
+     */
+    initialize(
+      settings: IntegrationsSettings,
+      options: InitOptions
+    ): AnalyticsJS;
+
+    /**
+     * Initialize with the given integration `settings` and `options`.
+     *
+     * Aliased to `init` for convenience.
+     */
+    init(settings: IntegrationsSettings, options: InitOptions): AnalyticsJS;
+
+    /**
+     * Set the user's `id`.
+     */
+    setAnonymousId(id: string): AnalyticsJS;
+
+    /**
+     * Add an integration.
+     */
+    add(integration: { name: string | number }): AnalyticsJS;
+
+    /**
+     * Identify a user by optional `id` and `traits`.
+     */
+    identify(
+      id: string,
+      traits: unknown,
+      options: SegmentOpts,
+      fn: Function | SegmentOpts
+    ): AnalyticsJS;
+
+    /**
+     * Return the current user.
+     */
+    user(): object;
+
+    /**
+     * Identify a group by optional `id` and `traits`. Or, if no arguments are
+     * supplied, return the current group.
+     */
+    group(
+      id: string,
+      traits: unknown,
+      options: unknown,
+      fn: unknown
+    ): AnalyticsJS;
+
+    /**
+     * Track an `event` that a user has triggered with optional `properties`.
+     */
+    track(
+      event: string,
+      properties: unknown,
+      options: unknown,
+      fn: unknown
+    ): AnalyticsJS;
+
+    /**
+     * Helper method to track an outbound link that would normally navigate away
+     * from the page before the analytics calls were sent.
+     *
+     * BACKWARDS COMPATIBILITY: aliased to `trackClick`.
+     */
+    trackClick(
+      links: Element | Array<unknown>,
+      event: any,
+      properties?: any
+    ): AnalyticsJS;
+
+    /**
+     * Helper method to track an outbound link that would normally navigate away
+     * from the page before the analytics calls were sent.
+     *
+     * BACKWARDS COMPATIBILITY: aliased to `trackClick`.
+     */
+    trackLink(
+      links: Element | Array<unknown>,
+      event: any,
+      properties?: any
+    ): AnalyticsJS;
+
+    /**
+     * Set the user's `id`.
+     */
+    setAnonymousId(id: string): AnalyticsJS;
+
+    /**
+     * Helper method to track an outbound form that would normally navigate away
+     * from the page before the analytics calls were sent.
+     *
+     * BACKWARDS COMPATIBILITY: aliased to `trackSubmit`.
+     */
+    trackSubmit(
+      forms: Element | Array<unknown>,
+      event: any,
+      properties?: any
+    ): AnalyticsJS;
+
+    /**
+     * Helper method to track an outbound form that would normally navigate away
+     * from the page before the analytics calls were sent.
+     *
+     * BACKWARDS COMPATIBILITY: aliased to `trackSubmit`.
+     */
+    trackForm(
+      forms: Element | Array<unknown>,
+      event: any,
+      properties?: any
+    ): AnalyticsJS;
+
+    /**
+     * Trigger a pageview, labeling the current page with an optional `category`,
+     * `name` and `properties`.
+     */
+    page(
+      category: string,
+      name: string,
+      properties: any,
+      options: any,
+      fn: unknown
+    ): AnalyticsJS;
+
+    /**
+     * Merge two previously unassociated user identities.
+     */
+    alias(
+      to: string,
+      from?: string,
+      options?: unknown,
+      fn?: unknown
+    ): AnalyticsJS;
+
+    /**
+     * Register a `fn` to be fired when all the analytics services are ready.
+     */
+    ready(fn: Function): AnalyticsJS;
+
+    /**
+     * Set the `timeout` (in milliseconds) used for callbacks.
+     */
+    timeout(timeout: number): void;
+
+    /**
+     * Enable or disable debug.
+     */
+    debug(str: string | boolean): void;
+
+    /**
+     * Reset group and user traits and id's.
+     */
+    reset(): void;
+
+    /**
+     * Normalize the given `msg`.
+     */
+    normalize(msg: { context: { page }; anonymousId: string }): object;
+
+    /**
+     * No conflict support.
+     */
+    noConflict(): AnalyticsJS;
+  }
+}
+
+declare var analytics: SegmentAnalytics.AnalyticsJS;
+
+declare module '@segment/analytics.js-core' {
+  var analytics: SegmentAnalytics.AnalyticsJS;
+  export default analytics;
+}