From ecab30d5cc51964eebda94e8857b35461e73dc06 Mon Sep 17 00:00:00 2001 From: Ryan Garver Date: Tue, 13 Dec 2022 11:07:52 -0800 Subject: [PATCH] Configure typedoc feat(docs): Initial documentation, fixes #11 --- .gitignore | 4 +++- package.json | 4 +++- src/SubscribePro.ts | 30 +++++++++++++++++++++++ src/V3/ResourceServiceBase.ts | 45 +++++++++++++++++++++++++++++++++-- yarn.lock | 44 ++++++++++++++++++++++++++++++++++ 5 files changed, 123 insertions(+), 4 deletions(-) diff --git a/.gitignore b/.gitignore index 6b73234..7d0a5ae 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,5 @@ .yarnrc lib -node_modules/ \ No newline at end of file +node_modules/ +docs/ + diff --git a/package.json b/package.json index 8f92bbf..543d5a4 100644 --- a/package.json +++ b/package.json @@ -11,7 +11,8 @@ "lint": "eslint -c .eslintrc.js --ext .ts src/", "prepack": "yarn build", "prepublish": "yarn test && yarn lint", - "semantic-release": "semantic-release" + "semantic-release": "semantic-release", + "docs": "typedoc --out docs --excludeNotDocumented --entryPointStrategy expand --exclude \"**/__tests__/**/*.ts\" src/" }, "repository": { "type": "git", @@ -35,6 +36,7 @@ "prettier": "^2.8.0", "semantic-release": "^19.0.5", "ts-jest": "^29.0.3", + "typedoc": "^0.23.22", "typescript": "^4.9.3" }, "files": [ diff --git a/src/SubscribePro.ts b/src/SubscribePro.ts index 1233547..7b8beec 100644 --- a/src/SubscribePro.ts +++ b/src/SubscribePro.ts @@ -8,7 +8,11 @@ export type Config = { environmentKey: string; }; +/** + * Namespace for all SubscribePro API calls. + */ export class SubscribePro { + private static _client: Client; private static _config: Config & { endpointUrl: string } = { endpointUrl: 'https://api.subscribepro.com', @@ -16,16 +20,42 @@ export class SubscribePro { environmentKey: '', }; + /** + * Namespace for the V2 SubscribePro API calls. + */ static V2 = V2; + + /** + * Namespace for the V3 SubscribePro API calls. + */ static V3 = V3; + /** + * This instance is pre-configured with the endpoint URL and access token and + * will be used by default for all API calls. + * + * @returns The client used to make API calls. + */ static get client() { return SubscribePro._client; } + + /** + * The configuration used to create the client. + * + * @returns The configuration including endpoint URL and access token. + */ static get config() { return SubscribePro._config; } + /** + * Stores the configuration and iniitalizes the client with this + * configuration. + * + * @param config - The configuration to use for the client. This should + * include the `endpointURL` and `accessToken`. + */ static configure(config: Config) { SubscribePro._config = {...SubscribePro.config, ...config}; this._client = new Client({endpointUrl: SubscribePro.config.endpointUrl, accessToken: SubscribePro.config.accessToken}); diff --git a/src/V3/ResourceServiceBase.ts b/src/V3/ResourceServiceBase.ts index 1ee6e78..fb02209 100644 --- a/src/V3/ResourceServiceBase.ts +++ b/src/V3/ResourceServiceBase.ts @@ -9,14 +9,42 @@ interface ResourceService { processJSONToCollection(json: JSONObject | null): CollectionType | null; }; +/** + * Base class for all resource services. + * @internal + */ export abstract class ResourceServiceBase { + /** + * @returns The path to the collection of resources. + * @internal + */ abstract collectionPath():string; + + /** + * @param id - The id of the resource. + * @returns The path to the resource. + * @internal + */ abstract resourcePath({id}:{id:string|number}):string; + /** + * Converts a JSON object to a RecordType. + * + * @param json - The JSON object to convert or null. + * @returns The converted RecordType or null. + * @internal + */ processJSONToRecord(json: JSONObject | null): RecordType | null { return json ? json as RecordType : null; } + /** + * Converts a JSON object to a CollectionType. + * + * @param json - The JSON object to convert or null. + * @returns The converted CollectionType or null. + * @internal + */ processJSONToCollection(json: JSONObject | null): CollectionType | null { return json ? json as CollectionType : null; } @@ -24,13 +52,26 @@ export abstract class ResourceServiceBase = new (...args: any[]) => TResult; - +interface IFaceResourceReadable { + findById({client, id}:{client?: Client, id:string|number}): Promise; +} +/** + * Adds a `findById` method to the base class. + * @internal + * + * @param Base - The base class to extend that inherits from + * ResourceServiceBase<> + * @typeParam T - The base class to extend that inherits from. Example: `typeof Base` + * @typeParam RecordType - The type of the record. + * @typeParam CollectionType - The type of the collection. Defaults to `RecordType[]` + * @returns + */ export function ResourceReadable< T extends ResourceServiceBaseConstructor>, RecordType, CollectionType=RecordType[] >(Base: T) { - return class extends Base { + return class extends Base implements IFaceResourceReadable { async findById({client, id}:{client?: Client, id:string|number}): Promise { client ||= SubscribePro.client; diff --git a/yarn.lock b/yarn.lock index 19cad35..77b0b21 100644 --- a/yarn.lock +++ b/yarn.lock @@ -3314,6 +3314,11 @@ json5@^2.2.1: resolved "https://registry.yarnpkg.com/json5/-/json5-2.2.1.tgz#655d50ed1e6f95ad1a3caababd2b0efda10b395c" integrity sha512-1hqLFMSrGHRHxav9q9gNjJ5EXznIxGVO09xQRrwplcS8qs28pZ8s8hupZAmqDwZUmVZ2Qb2jnyPOWcDH8m8dlA== +jsonc-parser@^3.0.0: + version "3.2.0" + resolved "https://registry.yarnpkg.com/jsonc-parser/-/jsonc-parser-3.2.0.tgz#31ff3f4c2b9793f89c67212627c51c6394f88e76" + integrity sha512-gfFQZrcTc8CnKXp6Y4/CBT3fTc0OVuDofpre4aEeEpSBPV5X5v4+Vmx+8snU7RLPrNHPKSgLxGo9YuQzz20o+w== + jsonfile@^6.0.1: version "6.1.0" resolved "https://registry.yarnpkg.com/jsonfile/-/jsonfile-6.1.0.tgz#bc55b2634793c679ec6403094eb13698a6ec0aae" @@ -3568,6 +3573,11 @@ lru-cache@^7.4.4, lru-cache@^7.5.1, lru-cache@^7.7.1: resolved "https://registry.yarnpkg.com/lru-cache/-/lru-cache-7.14.1.tgz#8da8d2f5f59827edb388e63e459ac23d6d408fea" integrity sha512-ysxwsnTKdAx96aTRdhDOCQfDgbHnt8SK0KY8SEjO0wHinhWOFTESbjVCMPbU1uGXg/ch4lifqx0wfjOawU2+WA== +lunr@^2.3.9: + version "2.3.9" + resolved "https://registry.yarnpkg.com/lunr/-/lunr-2.3.9.tgz#18b123142832337dd6e964df1a5a7707b25d35e1" + integrity sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow== + make-dir@^3.0.0: version "3.1.0" resolved "https://registry.yarnpkg.com/make-dir/-/make-dir-3.1.0.tgz#415e967046b3a7f1d185277d84aa58203726a13f" @@ -3636,6 +3646,11 @@ marked@^4.0.10: resolved "https://registry.yarnpkg.com/marked/-/marked-4.2.3.tgz#bd76a5eb510ff1d8421bc6c3b2f0b93488c15bea" integrity sha512-slWRdJkbTZ+PjkyJnE30Uid64eHwbwa1Q25INCAYfZlK4o6ylagBy/Le9eWntqJFoFT93ikUKMv47GZ4gTwHkw== +marked@^4.0.19: + version "4.2.4" + resolved "https://registry.yarnpkg.com/marked/-/marked-4.2.4.tgz#5a4ce6c7a1ae0c952601fce46376ee4cf1797e1c" + integrity sha512-Wcc9ikX7Q5E4BYDPvh1C6QNSxrjC9tBgz+A/vAhp59KXUgachw++uMvMKiSW8oA85nopmPZcEvBoex/YLMsiyA== + meow@^8.0.0: version "8.1.2" resolved "https://registry.yarnpkg.com/meow/-/meow-8.1.2.tgz#bcbe45bda0ee1729d350c03cffc8395a36c4e897" @@ -4746,6 +4761,15 @@ shebang-regex@^3.0.0: resolved "https://registry.yarnpkg.com/shebang-regex/-/shebang-regex-3.0.0.tgz#ae16f1644d873ecad843b0307b143362d4c42172" integrity sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A== +shiki@^0.11.1: + version "0.11.1" + resolved "https://registry.yarnpkg.com/shiki/-/shiki-0.11.1.tgz#df0f719e7ab592c484d8b73ec10e215a503ab8cc" + integrity sha512-EugY9VASFuDqOexOgXR18ZV+TbFrQHeCpEYaXamO+SZlsnT/2LxuLBX25GGtIrwaEVFXUAbUQ601SWE2rMwWHA== + dependencies: + jsonc-parser "^3.0.0" + vscode-oniguruma "^1.6.1" + vscode-textmate "^6.0.0" + signal-exit@^3.0.3, signal-exit@^3.0.7: version "3.0.7" resolved "https://registry.yarnpkg.com/signal-exit/-/signal-exit-3.0.7.tgz#a9a1767f8af84155114eaabd73f99273c8f59ad9" @@ -5170,6 +5194,16 @@ type-fest@^1.0.2: resolved "https://registry.yarnpkg.com/type-fest/-/type-fest-1.4.0.tgz#e9fb813fe3bf1744ec359d55d1affefa76f14be1" integrity sha512-yGSza74xk0UG8k+pLh5oeoYirvIiWo5t0/o3zHHAO2tRDiZcxWP7fywNlXhqb6/r6sWvwi+RsyQMWhVLe4BVuA== +typedoc@^0.23.22: + version "0.23.22" + resolved "https://registry.yarnpkg.com/typedoc/-/typedoc-0.23.22.tgz#e25281ca816cd92ecfdaf3ec336d27e7bebb69ac" + integrity sha512-5sJkjK60xp8A7YpcYniu3+Wf0QcgojEnhzHuCN+CkdpQkKRhOspon/9+sGTkGI8kjVkZs3KHrhltpQyVhRMVfw== + dependencies: + lunr "^2.3.9" + marked "^4.0.19" + minimatch "^5.1.0" + shiki "^0.11.1" + typescript@^4.9.3: version "4.9.3" resolved "https://registry.yarnpkg.com/typescript/-/typescript-4.9.3.tgz#3aea307c1746b8c384435d8ac36b8a2e580d85db" @@ -5260,6 +5294,16 @@ validate-npm-package-name@^4.0.0: dependencies: builtins "^5.0.0" +vscode-oniguruma@^1.6.1: + version "1.7.0" + resolved "https://registry.yarnpkg.com/vscode-oniguruma/-/vscode-oniguruma-1.7.0.tgz#439bfad8fe71abd7798338d1cd3dc53a8beea94b" + integrity sha512-L9WMGRfrjOhgHSdOYgCt/yRMsXzLDJSL7BPrOZt73gU0iWO4mpqzqQzOz5srxqTvMBaR0XZTSrVWo4j55Rc6cA== + +vscode-textmate@^6.0.0: + version "6.0.0" + resolved "https://registry.yarnpkg.com/vscode-textmate/-/vscode-textmate-6.0.0.tgz#a3777197235036814ac9a92451492f2748589210" + integrity sha512-gu73tuZfJgu+mvCSy4UZwd2JXykjK9zAZsfmDeut5dx/1a7FeTk0XwJsSuqQn+cuMCGVbIBfl+s53X4T19DnzQ== + walk-up-path@^1.0.0: version "1.0.0" resolved "https://registry.yarnpkg.com/walk-up-path/-/walk-up-path-1.0.0.tgz#d4745e893dd5fd0dbb58dd0a4c6a33d9c9fec53e"