Zendesk ZAF typings

packages/zendesk/package.json

@@ -4,12 +4,17 @@
   "description": "",
   "main": "index.js",
   "scripts": {
-    "build": "node scripts/build.mjs"
+    "build": "node scripts/build.mjs",
+    "test": "npx tsd tsd_project"
   },
   "keywords": [],
   "author": "",
   "license": "ISC",
   "devDependencies": {
-    "fs-extra": "^10.1.0"
+    "fs-extra": "^10.1.0",
+    "tsd": "^0.25.0"
+  },
+  "dependencies": {
+    "typescript": "^4.9.4"
   }
 }

packages/zendesk/sdk/index.ts

@@ -1,33 +1,17 @@
 // The ZAFClient is injected in the index.html file when built / served.
 // See docs for help regarding the ZAFClient: https://developer.zendesk.com/apps/docs/developer-guide/getting_started
 
-interface IMetadata<T> {
-  appId: number;
-  installationId: number;
-  name: string;
-  plan: {
-    name: string;
-  };
-	settings?: T
-}
-
-interface IClient {
-  invoke: (cmd: string, arg: any) => void;
-  get: (getter: string) => any;
-  metadata: <U>() => IMetadata<U>;
-  request: <U>(data: Object) => Promise<U>;
-  on: (eventName: string, listener: (...args: any) => any) => void;
-}
+import type { ZafClient } from "./types/client/client";
 
 declare global {
-	interface Window {
-		ZAFClient: {
-			init: () => IClient
-		}
-	}
+  interface Window {
+    ZAFClient: {
+      init: () => ZafClient;
+    };
+  }
 }
 
-let zafClient: IClient;
+let zafClient: ZafClient;
 if (typeof window.ZAFClient === "undefined") {
   // eslint-disable-line no-undef
   throw new Error("ZAFClient cannot run outside Zendesk");

packages/zendesk/sdk/types/apps/index.ts

@@ -0,0 +1,5 @@
+import { Support } from "./support";
+
+export type Apps = {
+  Support: Support;
+};

packages/zendesk/sdk/types/apps/support/index.ts

@@ -0,0 +1,5 @@
+import { Locations } from "./locations";
+
+export type Support = {
+  Locations: Locations;
+};

packages/zendesk/sdk/types/apps/support/locations/index.ts

@@ -0,0 +1,7 @@
+import { NewTicketSidebar } from "./new_ticket_sidebar";
+import { TicketSidebar } from "./ticket_sidebar";
+
+export type Locations = {
+  ["ticket_sidebar"]: TicketSidebar;
+  ["new_ticket_sidebar"]: NewTicketSidebar;
+};

packages/zendesk/sdk/types/apps/support/locations/new_ticket_sidebar/index.ts

@@ -0,0 +1,5 @@
+import { Ticket } from "../objects/ticket";
+
+export type NewTicketSidebar = {
+  ["ticket"]: Ticket;
+};

packages/zendesk/sdk/types/apps/support/locations/objects/group/index.ts

@@ -0,0 +1,4 @@
+export type Group = {
+  id: number;
+  name: string;
+};

packages/zendesk/sdk/types/apps/support/locations/objects/ticket/index.ts

@@ -0,0 +1,36 @@
+import { Group } from "../group";
+import { User } from "../user";
+
+export type Ticket = {
+  createdAt: string;
+  description: string;
+  externalId: null | unknown;
+  emailCcs: unknown;
+  id: number;
+  isNew: boolean;
+  postSaveAction: string; // string enum to find
+  priority: string; // string enum to find
+  recipient: unknown;
+  sharedWith: unknown;
+  status: string; // string enum to find
+  subject: string;
+  tags: string[];
+  type: string; // string enum to find
+  updatedAt: string;
+  viewers: unknown;
+  brand: unknown;
+  comment: unknown;
+  form: unknown;
+  editor: unknown;
+  organization: unknown;
+  via: unknown;
+  conversation: unknown;
+  collaborators: unknown;
+  followers: unknown;
+  assignee: {
+		group: Group;
+		user: User;
+	};
+  requester: User;
+  comments: unknown;
+};

packages/zendesk/sdk/types/apps/support/locations/objects/user/identities/index.ts

@@ -0,0 +1,18 @@
+type IdentityType =
+  | "email"
+  | "twitter"
+  | "facebook"
+  | "google"
+  | "agent_forwarding"
+  | "phone_number";
+
+export type Identity<I = "email"> = {
+  id: number;
+  type: IdentityType;
+  value: string;
+  verified: boolean;
+  primary: boolean;
+  userId: number;
+  undeliverableCount: number;
+  deliverableState: I extends "email" ? "deliverable" | "undeliverable" : null;
+};

packages/zendesk/sdk/types/apps/support/locations/objects/user/index.ts

@@ -0,0 +1,26 @@
+import { Group } from "../group";
+import { Identity } from "./identities";
+import { Organization } from "./organizations";
+import { Timezone } from "./timezone";
+
+type UserRole = "end-user" | "agent" | "admin";
+
+export type User = {
+  alias: string | null;
+  avatarUrl: string;
+  details: string | null;
+  email: string;
+  externalId: string | null;
+  id: number;
+  identities: Identity[];
+  isSystemUser: boolean;
+  locale: string;
+  name: string;
+  notes: null;
+  role: UserRole;
+  signature: string | null;
+  tags: [];
+  timeZone: Timezone;
+  groups: Group[];
+  organizations: Organization[];
+};

packages/zendesk/sdk/types/apps/support/locations/objects/user/organizations/index.ts

@@ -0,0 +1,23 @@
+// TODO add support for custom fields
+
+import { Group } from "../../group";
+
+// TODO incomplete!
+type OrganizationField = {
+	name: string;
+	isVisible: boolean;
+}
+
+export type Organization = {
+	details: string | null;
+	domains: string;
+	externalId: string | null;
+	groups: Group;
+	id: number;
+	name: string;
+	notes: string | null;
+	sharedComments: boolean;
+	sharedTickets: boolean;
+	tags: string[];
+	organizationFields: OrganizationField[];
+}

packages/zendesk/sdk/types/apps/support/locations/objects/user/timezone/index.ts

@@ -0,0 +1,6 @@
+export type Timezone = {
+  name: string;
+  ianaName: string;
+  offset: number;
+  formattedOffset: string;
+};

packages/zendesk/sdk/types/apps/support/locations/ticket_sidebar/index.ts

@@ -0,0 +1,5 @@
+import { Ticket } from "../objects/ticket";
+
+export type TicketSidebar = {
+  ["ticket"]: Ticket;
+};

packages/zendesk/sdk/types/client/client.test.ts

@@ -0,0 +1,12 @@
+import { expectType } from "tsd";
+
+import zafClient from "../..";
+
+// wrpapper around tests to be abe to use async/await
+const ClientGet = async () => {
+  const idData = await zafClient.get("ticket.id");
+  expectType<number>(idData["ticket.id"]);
+
+  const arrayOfTags = await zafClient.get("ticket.tags");
+  expectType<string[]>(arrayOfTags["ticket.tags"]);
+};

packages/zendesk/sdk/types/client/client.ts

@@ -0,0 +1,18 @@
+import { NestedPaths } from "../utilities";
+import { GetData, GettableLocations } from "./get";
+
+type ZendeskApiResponse<U> = U & {
+  errors: {}; // need to reproduce errors somehow to property type it
+};
+
+export type ZafClient = {
+  invoke: (cmd: string, arg: any) => void;
+
+  get: <Path extends NestedPaths<GettableLocations>>(
+    key: Path
+  ) => Promise<ZendeskApiResponse<GetData<Path>>>;
+
+  metadata: <U>() => Metadata<U>;
+  request: <U>(data: Object) => Promise<U>;
+  on: (eventName: string, listener: (...args: any) => any) => void;
+};

packages/zendesk/sdk/types/client/get.ts

@@ -0,0 +1,9 @@
+import { Locations as AllLocations } from "../apps/support/locations";
+import { NestedPaths, TypeFromPath } from "../utilities";
+
+type LocationsKeys = keyof AllLocations;
+export type GettableLocations = AllLocations[LocationsKeys];
+
+export type GetData<Key extends NestedPaths<GettableLocations>> = {
+	[key in Key]: TypeFromPath<GettableLocations, key>;
+}

packages/zendesk/sdk/types/metadata/metadata.ts

@@ -0,0 +1,9 @@
+type Metadata<T> = {
+  appId: number;
+  installationId: number;
+  name: string;
+  plan: {
+    name: string;
+  };
+  settings?: T;
+};

packages/zendesk/sdk/types/utilities/index.ts

@@ -0,0 +1,62 @@
+export type Primitive = string | number | symbol;
+
+type GenericObject = Record<Primitive, unknown>;
+
+type Join<
+  L extends Primitive | undefined,
+  R extends Primitive | undefined
+> = L extends string | number
+  ? R extends string | number
+    ? `${L}.${R}`
+    : L
+  : R extends string | number
+  ? R
+  : undefined;
+
+type Union<
+  L extends unknown | undefined,
+  R extends unknown | undefined
+> = L extends undefined
+  ? R extends undefined
+    ? undefined
+    : R
+  : R extends undefined
+  ? L
+  : L | R;
+
+/**
+ * NestedPaths
+ * Get all the possible paths of an object
+ * @example
+ * type Keys = NestedPaths<{ a: { b: { c: string } }>
+ * // 'a' | 'a.b' | 'a.b.c'
+ */
+export type NestedPaths<
+  T extends GenericObject,
+  Prev extends Primitive | undefined = undefined,
+  Path extends Primitive | undefined = undefined
+> = {
+  [K in keyof T]: T[K] extends GenericObject
+    ? NestedPaths<T[K], Union<Prev, Path>, Join<Path, K>>
+    : Union<Union<Prev, Path>, Join<Path, K>>;
+}[keyof T];
+
+/**
+ * TypeFromPath
+ * Get the type of the element specified by the path
+ * @example
+ * type TypeOfAB = TypeFromPath<{ a: { b: { c: string } }, 'a.b'>
+ * // { c: string }
+ */
+export type TypeFromPath<
+  T extends GenericObject,
+  Path extends string // Or, if you prefer, NestedPaths<T>
+> = {
+  [K in Path]: K extends keyof T
+    ? T[K]
+    : K extends `${infer P}.${infer S}`
+    ? T[P] extends GenericObject
+      ? TypeFromPath<T[P], S>
+      : never
+    : never;
+}[Path];

packages/zendesk/tsconfig.json

@@ -1,5 +1,10 @@
 {
   "compilerOptions": {
-    "typeRoots": ["./@types"],
+    "target": "es2016",
+    "module": "commonjs",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true
   }
 }

packages/zendesk/tsd_project/README.md

@@ -0,0 +1,4 @@
+## What is this?
+
+Dummy project to force `tsd` package to play nicely with testing types
+https://github.com/SamVerschueren/tsd/issues/32#issuecomment-778650556

packages/zendesk/tsd_project/package.json

@@ -0,0 +1,6 @@
+{
+	"types": "dummy.d.ts",
+	"tsd": {
+		"directory": "../sdk"
+	}
+}