feat: add 'Viewer' class disentangled from 'User' (#48)

* viewer refactor

* edit release notes

* merge baseatlasclass refactor

* Update publish-docs.yml

* organizations use fetchAttributes

* add ellipsis linting

* remove duplicate openapi types

* fix import paths

* Update index.ts

* import consistency

---------

Co-authored-by: Robert Lesser <[email protected]>

.github/workflows/publish-docs.yml

@@ -0,0 +1,42 @@
+name: Publish TSDoc to GitHub Pages
+
+permissions:
+  contents: write
+  actions: read
+  checks: write
+  deployments: write
+  issues: write
+  packages: read
+  pull-requests: write
+  statuses: write
+
+on:
+  push:
+    branches:
+      - main
+      - docs
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v2
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Generate documentation
+        run: npx typedoc
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs

.gitignore

@@ -4,3 +4,4 @@ src/openapi.d.ts
 etc/openapi.json
 private
 dist
+docs

ellipsis.yaml

@@ -0,0 +1,17 @@
+version: 1.3
+
+about:
+  - This is a codebase for the Typescript SDK of Nomic Atlas. Atlas is a web based service that allows users to store and interact with unstructure datasets. The SDK should be useful for developers who want to interact with the Atlas API in both Node and browser environments.
+
+pr_review:
+  confidence_threshold: 0.7
+  rules:
+    - "Code should be DRY (Don't Repeat Yourself)"
+    - 'There should no secrets or credentials in the code'
+    - 'Extremely Complicated Code Needs Comments'
+    - 'Use Descriptive Variable and Constant Names'
+    - "Requests to APIs must have error handling, they shouldn't solely just the network error"
+    - 'Use retries when calling external API services'
+    - "Don't log sensitive data"
+    - 'Follow the Single Responsibility Principle'
+    - 'Function and Method Naming Should Follow Consistent Patterns'

package.json

@@ -45,6 +45,7 @@
     "ts-node": "^10.9.1",
     "ts-node-dev": "^2.0.0",
     "tsconfig-paths": "^4.2.0",
+    "typedoc": "^0.25.13",
     "typescript": "^4.9.5",
     "uvu": "^0.5.6"
   },

src/embedding.ts

@@ -1,3 +1,4 @@
+import { AtlasViewer } from './viewer.js';
 import { BaseAtlasClass, AtlasUser } from './user.js';
 
 type TaskType =
@@ -49,7 +50,7 @@ const BATCH_SIZE = 32;
  * const embeddings = await embedder.embed(documents)
  * ```
  *
- * GOOD -- Nomic will combine your small requests into several medium-size
+ * GOOD -- Nomic will combine your small requests into several medium-size ones.
  * ```js
  * const documents = ["Once upon a time", "there was a girl named Goldilocks", …, "and they all lived happily ever after"]
  * const embedder = new Embedder(myApiKey)
@@ -60,7 +61,7 @@ const BATCH_SIZE = 32;
  * const embeddings = await Promise.all(promises)
  * ```
  *
- * BAD -- You will generate many small, inefficient requests
+ * BAD -- You will generate many small, inefficient requests.
  * ```js
  *  * const documents = ["Once upon a time", "there was a girl named Goldilocks", …, "and they all lived happily ever after"]
  * const embedder = new Embedder(myApiKey)
@@ -98,28 +99,32 @@ export class Embedder extends BaseAtlasClass<{}> {
    */
   constructor(apiKey: string, options: EmbedderOptions);
   constructor(user: AtlasUser, options: EmbedderOptions);
-  constructor(input: string | AtlasUser, options: EmbedderOptions = {}) {
+  constructor(viewer: AtlasViewer, options: EmbedderOptions);
+  constructor(
+    input: string | AtlasUser | AtlasViewer,
+    options: EmbedderOptions = {}
+  ) {
     const { model, taskType } = {
       // Defaults
       model: 'nomic-embed-text-v1.5' as EmbeddingModel,
       taskType: 'search_document' as TaskType,
       ...options,
     };
-    let user: AtlasUser;
+    let viewer: AtlasViewer | AtlasUser;
     if (typeof input === 'string') {
-      user = new AtlasUser({
+      viewer = new AtlasViewer({
         apiKey: input,
       });
     } else {
-      user = input;
+      viewer = input;
     }
     // Handle authentication the normal way.
-    super(user);
+    super(viewer);
     this.model = model;
     this.taskType = taskType;
   }
 
-  endpoint(): string {
+  protected endpoint(): string {
     throw new Error('Embedders do not have info() property.');
   }
 
@@ -254,7 +259,7 @@ export async function embed(
 ): Promise<Embedding | Embedding[]> {
   const machine =
     apiKey === undefined
-      ? new Embedder(new AtlasUser({ useEnvToken: true }), options)
+      ? new Embedder(new AtlasViewer({ useEnvToken: true } as const), options)
       : new Embedder(apiKey, options);
 
   if (typeof value === 'string') {

src/global.d.ts

@@ -3,9 +3,22 @@ declare namespace Atlas {
   type LoadProjectOptions = {
     project_id: UUID;
   };
+
+  /**
+   * Options for the nearest neighbors query.
+   */
   type NNOptions = {
+    /**
+     * The datum_ids (i.e., user-specified keys) to query for.
+     */
     datum_ids?: string[];
+    /**
+     * The Atom IDs (Nomic-generated integers) to query for.
+     */
     atom_ids?: string[];
+    /**
+     * The number of nearest neighbors to return.
+     */
     k?: number;
   };
 
@@ -39,4 +52,45 @@ declare namespace Atlas {
   };
   type Payload = Record<string, any> | Uint8Array | null;
   type AtlasUser = {};
+
+  type Envlogin = {
+    useEnvToken: true;
+    apiLocation?: never;
+    apiKey?: never;
+    bearerToken?: never;
+  };
+  type ApiKeyLogin = {
+    useEnvToken?: never;
+    apiLocation?: string;
+    apiKey: string;
+    bearerToken?: never;
+  };
+  type BearerTokenLogin = {
+    useEnvToken?: never;
+    bearerToken: string;
+    apiLocation?: string;
+    apiKey?: never;
+  };
+  type AnonViewerLogin = {
+    useEnvToken?: never;
+    bearerToken?: never;
+    apiLocation?: string;
+    apiKey?: never;
+  };
+  type LoginParams =
+    | Envlogin
+    | ApiKeyLogin
+    | BearerTokenLogin
+    | AnonViewerLogin;
+
+  type ApiCallOptions = {
+    octetStreamAsUint8?: boolean;
+  };
+
+  type TokenRefreshResponse = any;
+  interface Credentials {
+    refresh_token: string | null;
+    token: string;
+    expires: number;
+  }
 }