feat: validate clarifai url with template literal types

Clarifai · Mar 16, 2024 · 31a0333 · 31a0333
1 parent 8d2d7db
commit 31a0333
Show file tree

Hide file tree

Showing 4 changed files with 46 additions and 11 deletions.
diff --git a/src/client/app.ts b/src/client/app.ts
@@ -21,7 +21,7 @@ import {
   DeleteModulesRequest,
 } from "clarifai-nodejs-grpc/proto/clarifai/api/service_pb";
 import { UserError } from "../errors";
-import { ClarifaiUrlHelper } from "../urls/helper";
+import { ClarifaiAppUrl, ClarifaiUrlHelper } from "../urls/helper";
 import { mapParamsToRequest, promisifyGrpcCall } from "../utils/misc";
 import { AuthConfig, PaginationRequestParams } from "../utils/types";
 import { Lister } from "./lister";
@@ -37,25 +37,36 @@ import {
 import { TRAINABLE_MODEL_TYPES } from "../constants/model";
 import { StatusCode } from "clarifai-nodejs-grpc/proto/clarifai/api/status/status_code_pb";
 
+type AppConfig =
+  | {
+      url: ClarifaiAppUrl;
+      authConfig: Omit<AuthConfig, "appId"> & { appId?: undefined };
+    }
+  | {
+      url?: undefined;
+      authConfig: AuthConfig;
+    };
+
 export class App extends Lister {
   private appInfo: GrpcApp;
 
-  constructor({ url, authConfig }: { url?: string; authConfig: AuthConfig }) {
+  constructor({ url, authConfig }: AppConfig) {
     if (url && authConfig.appId) {
       throw new UserError("You can only specify one of url or app_id.");
     }
 
     if (url) {
       const [userId, appId] = ClarifaiUrlHelper.splitClarifaiAppUrl(url);
       if (userId) authConfig.userId = userId;
+      // @ts-expect-error - since url is parsed, we need to set appId here
       if (appId) authConfig.appId = appId;
     }
 
-    super({ authConfig: authConfig });
+    super({ authConfig: authConfig as AuthConfig });
 
     this.appInfo = new GrpcApp();
     this.appInfo.setUserId(authConfig.userId);
-    this.appInfo.setId(authConfig.appId);
+    this.appInfo.setId(authConfig.appId!);
   }
 
   async *listDataSets({

diff --git a/src/client/model.ts b/src/client/model.ts
@@ -10,7 +10,7 @@ import {
   SingleModelResponse,
 } from "clarifai-nodejs-grpc/proto/clarifai/api/service_pb";
 import { UserError } from "../errors";
-import { ClarifaiUrlHelper } from "../urls/helper";
+import { ClarifaiUrl, ClarifaiUrlHelper } from "../urls/helper";
 import {
   BackoffIterator,
   mapParamsToRequest,
@@ -64,7 +64,7 @@ export class Model extends Lister {
     authConfig = {},
   }:
     | {
-        url: string;
+        url: ClarifaiUrl;
         modelId?: undefined;
         modelVersion?: { id: string };
         authConfig?: AuthConfig;

diff --git a/src/client/workflow.ts b/src/client/workflow.ts
@@ -1,7 +1,7 @@
 import { AuthConfig } from "../utils/types";
 import { Lister } from "./lister";
 import { UserError } from "../errors";
-import { ClarifaiUrlHelper } from "../urls/helper";
+import { ClarifaiUrl, ClarifaiUrlHelper } from "../urls/helper";
 import {
   Input as GrpcInput,
   OutputConfig as GrpcOutputConfig,
@@ -28,7 +28,7 @@ type OutputConfig = { minValue: number };
 
 type WorkflowConfig =
   | {
-      url: string;
+      url: ClarifaiUrl;
       workflowId?: undefined;
       workflowVersion?: undefined;
       outputConfig?: OutputConfig;

diff --git a/src/urls/helper.ts b/src/urls/helper.ts
@@ -4,6 +4,17 @@ interface ClarifaiAuthHelper {
   ui: string;
 }
 
+type USERID = string;
+type APPID = string;
+type RESOURCE_TYPE = string;
+type RESOURCEID = string;
+type RESOURCE_VERSION_TYPE = string;
+type RESOURCE_VERSION_ID = string;
+export type ClarifaiUrl =
+  | `${string}://${string}/${USERID}/${APPID}/${RESOURCE_TYPE}/${RESOURCEID}/${RESOURCE_VERSION_TYPE}/${RESOURCE_VERSION_ID}`
+  | `${string}://${string}/${USERID}/${APPID}/${RESOURCE_TYPE}/${RESOURCEID}`;
+export type ClarifaiAppUrl = `${string}://${string}/${USERID}/${APPID}`;
+
 export class ClarifaiUrlHelper {
   private auth: ClarifaiAuthHelper;
   private moduleManagerImvId: string;
@@ -109,10 +120,14 @@ export class ClarifaiUrlHelper {
 
   /**
    * Splits a Clarifai app URL into its component parts.
+   * clarifai.com uses fully qualified urls to resources.
+   * They are in the format of:
+   * https://clarifai.com/{user_id}/{app_id}
+   *
    * @param url The Clarifai app URL.
    * @returns A tuple containing userId and appId.
    */
-  static splitClarifaiAppUrl(url: string): [string, string] {
+  static splitClarifaiAppUrl(url: ClarifaiAppUrl): [string, string] {
     const o = new URL(url);
     const parts = o.pathname.split("/").filter((part) => part.length > 0);
     if (parts.length !== 3) {
@@ -125,11 +140,16 @@ export class ClarifaiUrlHelper {
 
   /**
    * Splits a Clarifai URL into its component parts, including optional resource version.
+   * clarifai.com uses fully qualified urls to resources.
+   * They are in the format of:
+   * https://clarifai.com/{user_id}/{app_id}/{resource_type}/{resource_id}/{resource_version_type}/{resource_version_id}
+   * Those last two are optional.
+   *
    * @param url The Clarifai URL.
    * @returns A tuple containing userId, appId, resourceType, resourceId, and optionally resourceVersionId.
    */
   static splitClarifaiUrl(
-    url: string,
+    url: ClarifaiUrl,
   ): [string, string, string, string, string?] {
     const o = new URL(url);
     const parts = o.pathname.split("/").filter((part) => part.length > 0);
@@ -145,10 +165,14 @@ export class ClarifaiUrlHelper {
 
   /**
    * Splits a module UI URL into its component IDs.
+   * Takes in a path like https://clarifai.com/zeiler/app/modules/module1/versions/2 to split it apart into it's IDs.
+   *
    * @param install The module UI URL.
    * @returns A tuple containing userId, appId, moduleId, and moduleVersionId.
    */
-  static splitModuleUiUrl(install: string): [string, string, string, string] {
+  static splitModuleUiUrl(
+    install: ClarifaiUrl,
+  ): [string, string, string, string] {
     const [userId, appId, resourceType, resourceId, resourceVersionId] =
       this.splitClarifaiUrl(install);
     if (resourceType !== "modules" || resourceVersionId === undefined) {