Merge pull request #26 from modzy/mds/docs

Add docs, minor type fixes

Author: mstanaland

.gitignore

@@ -26,7 +26,6 @@ node_modules
 # build
 dist
 types
-docs
 
 # misc
 .DS_Store

CHANGES.md

@@ -4,28 +4,42 @@ Version 1 of the SDK client only supported Node application because the final bu
 
 The previous documentation often incorrectly showed the results of the methods having direct returns. In reality, all methods return a promise that resolves to the data shown.
 
-- modzyClient initialization parameter change to single object. The `url` key is optional as it defaults to app.modzy.com
-- Removed `.getAllModels`. use getActiveModels() or call getModels() with no params.
-- Added `.getActiveModels`. Returns only the active models with more useful details
-- `.getModels` parameter change to single object.
-- `.getModel` renamed to `.getModelById`
-- `.getModelByName` unchanged
-- `.getRelatedModels` removed because not useful
-- `.getModelVersions` renamed `.getModelVersionsById`
-- `.getModelVersion` renamed to `.getModelDetails`; parameter change to single object
-- `.getModelVersionInputSample` parameter change to single object
-- `.getModelVersionOutputSample` parameter change to single object
-- `.getJobHistory` parameter change to single object
-- `.submitJobText` parameter change to single object
-- `.submitJobEmbedded` parameter change to single object. No longer handles any parsing of the embedded file, assumes that the sources object has the file as a proper data URL. Use the utility `pathToDataUrl(path, mimeType)` for Node and `fileToDataUrl(file)` for browser.
-- `.submitJobFile` parameter change to single object. For the browser, the file needs to be base64 encoded. The modzyClient includes a built-in utility `.fileToDataUrl` to convert a File blob to base64. For Node JS, you specify the relative path as a string.
-- `.submitJobAWSS3` renamed to `.submitJobAwsS3`; parameter change to single object
-- `.submitJobJDBC` parameter change to single object
-- `.getJob` unchanged
-- `.cancelJob` unchanged
-- `.getResult` unchanged
-- Added `.getOutputContents` which gets the contents of a specific job output
-- `.blockUntilComplete` renamed to `.blockUntilJobComplete`; takes just the jobId as a parameter; adds an optional second parameter that is a config object. Currently the only config key is `timeout` where you specify the number of milliseconds between checks for job completion.
-- Adds `.getProcessingEngineStatus` which returns an array of actively running processing engines and their statuses
-- Adds `.fileToDataUrl`, (browser only) a utility to convert a File blob to a base64 data URL
-- Adds `.pathToDataUrl`, (Node only) a utility to convert a file to a base64 data URL
+### Client initialization
+
+- `ModzyClient` constructor parameter changed to single object. The `url` key is optional as it defaults to app.modzy.com
+
+### Model methods
+
+- Added `getActiveModels`. It always returns _all_ active models with more useful details. This api call does not support pagination.
+- Removed `getAllModels`. Use `getModels` with no params to get the first 500 models or `getActiveModels()`.
+- Removed `getRelatedModels` as the results were most often not useful
+- Renamed `getModel` to `getModelById`
+- Rename `getModelVersions` to `getModelVersionsById`
+- Renamed `getModelVersion` to `getModelDetails`; parameter change to single object
+- `getModels` parameter change to single object.
+- `getModelVersionInputSample` parameter change to single object
+- `getModelVersionOutputSample` parameter change to single object
+
+### Job status and result methods
+
+- Added `getOutputContents` which gets the contents of a specific job output - especially useful if the output is a binary file
+- Added `getProcessingEngineStatus` which returns an array of actively running processing engines and their statuses
+- Renamed `blockUntilComplete` to `blockUntilJobComplete`. It takes just the jobId as a parameter; adds an optional second parameter that is a config object to specify the number of milliseconds between checks for job completion.
+- `getJobHistory` parameter change to single object
+
+### Job submission methods
+
+- `submitJobText` parameter change to single object
+- `submitJobEmbedded` parameter change to single object. This method no longer handles any parsing of the embedded file and assumes that the sources object has the file as a proper data URL. You can use the new utilities `pathToDataUrl(path, mimeType)` for Node or `fileToDataUrl(file)` for browser to construct the `sources` object.
+- `submitJobFile` parameter change to single object. For the browser, the file needs to be base64 encoded. The modzyClient includes a built-in utility `fileToDataUrl` to convert a File blob to base64. For Node JS, you specify the relative path as a string.
+- `submitJobAWSS3` renamed to `submitJobAwsS3`; parameter change to single object
+- `submitJobJDBC` parameter change to single object
+
+### New utilities
+
+- Added `fileToDataUrl`, (browser only) a utility to convert a File blob to a base64 data URL
+- Added `pathToDataUrl`, (Node only) a utility to convert a file to a base64 data URL
+
+### Samples
+
+- Added sample React components

README.md

@@ -1,6 +1,6 @@
 # Modzy JavaScript SDK
 
-Modzy's Javascript SDK simplifies tasks such as querying models, submitting jobs, and returning results. It supports both NodeJS and browser JavaScript applications using the output target of your build system to know which code to use.
+Modzy's Javascript SDK simplifies tasks such as querying models, submitting jobs, and returning results. It supports both Node.js and browser JavaScript applications using the output target of your build system to know which code to use.
 
 ## Visit [docs.modzy.com](https://docs.modzy.com/docs/javascript) for docs, guides, API and more.
 
@@ -27,7 +27,9 @@ import { ModzyClient } from "@modzy/modzy-sdk";
 
 ## Initialize
 
-To initialize the modzy client you need an [api key](https://docs.modzy.com/docs/getting-started#key-download-your-api-key). If using an installation of Modzy other than app.modzy.com, you'll also need the url for your instance of Modzy.
+To initialize `ModzyClient`, you need an [api key](https://docs.modzy.com/docs/getting-started#key-download-your-api-key). If using an installation of Modzy other than app.modzy.com, you'll also need to provide the url for your instance of Modzy. For debugging purposes, you can also turn on logging.
+
+⚠️ _Warning: Keep your API key secret. Do not include it in a git repo or store it on GitHub_
 
 ```javascript
 // app.modzy.com
@@ -42,22 +44,11 @@ const modzyClient = new ModzyClient({
 });
 ```
 
-⚠️ _Warning: Keep your API key secret. Do not include it in git repo or store it on GitHub_
-
 ---
 
-## Submit a job
-
-The ModzyClient has several methods for creating jobs based on the input type:
-
-- `submitJobText()`: For text inputs
-- `submitJobFile()`: For binaries
-- `submitJobEmbedded()`: For Base64 strings
-- `submitJobAwsS3()`: For inputs stored in S3
-- `submitJobJDBC()`: For inputs stored in databases
+## Basic usage
 
-The return of each of these methods is a promise that resolves to an object describing the submitted job, _not the job result!_
-The most important item in the job object is the `jobIdentifier` - you'll use this to check the status of the job and get the job results.
+Submit a job providing the model, version and input text:
 
 ```javascript
 const { jobIdentifier } = await modzyClient.submitJobText({
@@ -71,147 +62,24 @@ const { jobIdentifier } = await modzyClient.submitJobText({
 });
 ```
 
-In the sources object above, the key `"yourInputKey"` is named by you and can be anything, but "input.txt" is the required input name set by this particular model. You can find the input name(s) by going to model details > API for the model you want to use.
-
-Your can submit multiple input sets in a single job rather than submitting multiple jobs with a single input set. An example using the same model as above:
-
-```javascript
-const { jobIdentifier } = await modzyClient.submitJobText({
-  modelId: "ed542963de",
-  version: "1.0.1",
-  sources: {
-    myFirstInput: {
-      "input.txt": "Rain is the worst weather",
-    },
-    mySecondInput: {
-      "input.txt": "Partly cloudy is the best weather",
-    },
-  },
-});
-```
-
-Some models require 2 or more inputs to run. In that case, the sources object would look something like this:
-
-```javascript
-{
-  yourInputKey: {
-    "inputA": // ...contents of inputA,
-    "inputB": // ...contents of inputB,
-  },
-};
-```
-
-[Learn more about creating jobs.](https://docs.modzy.com/reference/create-a-job-1)
-
----
-
-## Wait for the job to complete
-
-Before you can get your job's result, you first have to wait for the job to finish. How long will that take? Well ... it's complicated. A job might finish in a few milliseconds, or it may take several minutes to finish running. How long depends on a numbers of factors such as model type, job queue length, how many processing engines are running, and the hardware being used.
-
-The JavaScript SDK has the method `blockUntilJobComplete()` to simplify waiting:
+Hold until the inference is complete:
 
 ```javascript
 await modzyClient.blockUntilJobComplete(jobIdentifier);
 ```
 
-As the name implies, this will block any subsequent code from running until the job is complete. It does this by creating a loop that checks the job status every two seconds until the job status comes back as finish. You can change the interval by passing in a new timeout value in milliseconds:
-
-```javascript
-await modzyClient.blockUntilJobComplete(jobIdentifier, { timeout: 500 });
-```
-
-If you'd rather check the status of the job yourself, you can use `getJob()`
-
-```javascript
-const { status } = await modzyClient.getJob(jobIdentifier);
-
-// status of "SUBMITTED" or "IN_PROGRESS" means the job hasn't finished
-// "COMPLETED", "COMPLETED_WITH_ERROR" or "TIMEDOUT" indicates the job has finished
-```
-
----
-
-## Get job results
-
-Once the job is done, you can fetch the result using `getResult()`. This returns a large object containing information about the job as well as the results. If the model returns multiple outputs, they will all be included in this single object.
+Get the output results:
 
 ```javascript
 const result = await modzyClient.getResult(jobIdentifier);
 ```
 
 ---
 
-## Getting a specific result output
-
-You can use `getOutputContents()` to fetch only the contents of a specific model output. This is especially useful if the output is a binary file. You need to know the model's output name(s), which you can get from the model details.
-
-Let's use the Text to Speech model on app.modzy.com as an example:
-
-```javascript
-// This code sample is for the browser, not Node
-
-// Submit the job
-const { jobIdentifier } = await modzyClient.submitJobText({
-  modelId: "uvdncymn6q",
-  version: "0.0.3",
-  sources: {
-    myInput: {
-      "input.txt": "I love the sound of robot voices!",
-    },
-  },
-});
-
-// Wait for the job to finish
-await modzyClient.blockUntilJobComplete(jobIdentifier);
-
-// Get the contents of the output named "results.wav" that the user submitted
-// with the key "myInput".
-// Note that the responseType is "blob" because this model output is a binary file.
-// The default responseType is "json".
-const speechContents = await modzyClient.getOutputContents({
-  jobId: jobIdentifier,
-  inputKey: "myInput",
-  outputName: "results.wav", // The output name must match the model's api!
-  responseType: "blob",
-});
-
-// create a link to download the file from the browser
-const url = window.URL.createObjectURL(
-  new Blob([speechContents], { type: "audio/wav" })
-);
-const link = document.createElement("a");
-link.href = url;
-link.setAttribute("download", "results.wav");
-document.body.appendChild(link);
-link.click();
-link.remove();
-```
-
-If you're writing a Node app, set the `responseType` to `"arraybuffer"`.
-
-```javascript
-// Node JS
-
-// Get the contents of the output named "results.wav" that the user submitted
-// with the key `myInput`.
-const speechContents = await modzyClient.getOutputContents({
-  jobId: speechJob.jobIdentifier,
-  inputKey: "myInput",
-  outputName: "results.wav",
-  responseType: "arraybuffer",
-});
-
-// write the file to disk
-fs.writeFileSync("./results.wav", speechContents);
-```
-
----
-
 ## Samples
 
 Check out our [samples](https://github.com/modzy/sdk-javascript/tree/main/samples) for details on specific use cases.
-Samples are intended to be run using Node, but most can also run in the browser. The `react examples` directory contains a couple of react components to show how you can use the browser to send files to, or retrieve files from Modzy. To run the samples using app.modzy.com, make sure to update the line `const API_KEY = process.env.MODZY_API_KEY;` to contain a real api key from your account.
+Samples are intended to be run using Node.js, but most can also run in the browser. The `react examples` directory contains a couple of react components to show how you can use the browser to send files to, or retrieve files from Modzy. To run the samples using app.modzy.com, make sure to update the line `const API_KEY = process.env.MODZY_API_KEY;` to contain a real api key from your account.
 
 ---