chore: update documentation

Author: Ehesp

docs.json

@@ -11,8 +11,6 @@
         ["Input", "/storage-image-processing-api/input"],
         ["Operations", "/storage-image-processing-api/operations"],
         ["Output", "/storage-image-processing-api/output"],
-        ["Caching", "/storage-image-processing-api/caching"],
-        ["Error Handling", "/storage-image-processing-api/error-handling"],
         ["Types", "/storage-image-processing-api/types"]
       ]
     ]

docs/storage-image-processing-api/caching.mdx

@@ -1 +1 @@
-### TODO Caching
+### Caching

docs/storage-image-processing-api/error-handling.mdx

@@ -1 +1 @@
-### TODO Error Handling
+### Error Handling

docs/storage-image-processing-api/index.mdx

@@ -42,10 +42,6 @@ During the installation of the extension, you will be prompted to specify a numb
 
   Cloud storage bucket, where the images to be processed are located.
 
-- **Cloud Storage path for caching images:**
-
-  A relative path in which the processed images are cached in the specified Cloud Storage bucket. If you prefer to store resized images at the default location, leave this field empty.
-
 - **Allowed CORS origins:**
 
   A comma-delimited value of allowed `CORS` origins. Use the default of `*` to allow all origins. This is useful to lock down your API and only allow your own website to embed the images directly. Note this will not prevent non-browser requests from accessing your API.
@@ -62,10 +58,74 @@ curl -X GET \
 - **`{LOCATION}`**: The Cloud Functions location that was specified during the installation of the extension.
 - **`{PROJECT_ID}`**: The Firebase project ID.
 
-### Operations
+### Operation usage
 
 The `operations` query parameter is a JSON array of operations to perform. Each operation is a JSON object with an `operation` property specifying the operation to perform and other properties depending on the operation.
+The parameter follows a couple of rules:
+
+1. The first operation in the array must be an `input` operation. This operation specifies the image to be processed. Read the [input](/input) operation documentation for more information.
+1. The last operation in the array must be an `output` operation. This operation specifies the `format` of the image to be created. Read the [output](/output) operation documentation for more information.
+
+The following example details a remote `input` operation and the `output` type:
+
+```js
+[
+  {
+    operation: 'input',
+    type: 'url',
+    url: 'https://example.com/image.jpg',
+  },
+  // Other operations...
+  {
+    operation: 'output',
+    format: 'webp',
+  },
+];
+```
 
-The first operation in the array must be an `input` operation. This operation specifies the image to be processed. Read the [input](/input) operation documentation for more information.
+Additional operations can be placed inbetween to process the image operation types outline in the [documentation](/operations), for example to flip then rotate the image 90 degrees:
+
+```js
+[
+  {
+    operation: 'input',
+    type: 'url',
+    url: 'https://example.com/image.jpg',
+  },
+  {
+    operation: 'flip',
+  },
+  {
+    operation: 'rotate',
+    angle: 90,
+  },
+  {
+    operation: 'output',
+    format: 'webp',
+  },
+];
+```
 
-Also, the last operation in the array must be an `output` operation. This operation specifies the `format` of the image to be created. Read the [output](/output) operation documentation for more information.
+### Providing the operations
+
+The `operations` query parameter accepts a strigified JSON object as a value. This should be encoded as a URI component, for example:
+
+```js
+const operations = [
+  {
+    operation: 'input',
+    type: 'url',
+    url: 'https://example.com/image.jpg',
+  },
+  {
+    operation: 'flip',
+  },
+  {
+    operation: 'output',
+    format: 'webp',
+  },
+];
+
+const encodedOperations = encodeURIComponent(JSON.stringify(operations));
+const url = `https://{LOCATION}-{PROJECT_ID}.cloudfunctions.net/ext-storage-image-processing-api-handler/process?operations=${encodedOperations}`;
+```

docs/storage-image-processing-api/input.mdx

@@ -1,5 +1,8 @@
 # Input
 
+The input operation specifies what image will be used as the source of the image processing. This can either be a path to a file on your storage bucket,
+a remote URL, or allow the extension to create an image on the fly.
+
 ## Google Cloud Storage
 
 This is a valid google cloud storage url of an existing image. For example:

extensions/storage-image-processing-api/POSTINSTALL.md

@@ -2,9 +2,36 @@
 
 You can test out this extension right away!
 
-Use the following URL to access the image processing API:
+1. Create an operations list, for example:
 
-[https://{param:LOCATION}-{param:PROJECT_ID}.cloudfunctions.net/ext-storage-image-processing-api-handler/process](https://{param:LOCATION}-{param:PROJECT_ID}.cloudfunctions.net/ext-storage-image-processing-api-handler/process)
+```js
+const operations = [
+  {
+    operation: 'input',
+    type: 'url',
+    url: 'https://images.unsplash.com/photo-1663659552548-25d7771802c9?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=774&q=80',
+  },
+  {
+    operation: 'grayscale',
+  },
+  {
+    operation: 'output',
+    format: 'webp',
+  },
+];
+```
+
+2. Stringify and encode the list:
+
+```js
+encodeURIComponent(JSON.stringify(operations))
+```
+
+3. Call the deployed `process` Cloud Function:
+
+[https://${PARAM:LOCATION}-${PARAM:PROJECT_ID}.cloudfunctions.net/ext-storage-image-processing-api-handler/process?operations=%5B%7B%22operation%22%3A%22input%22%2C%22type%22%3A%22url%22%2C%22url%22%3A%22https%3A%2F%2Fimages.unsplash.com%2Fphoto-1663659552548-25d7771802c9%3Fixlib%3Drb-1.2.1%26ixid%3DMnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8%26auto%3Dformat%26fit%3Dcrop%26w%3D774%26q%3D80%22%7D%2C%7B%22operation%22%3A%22grayscale%22%7D%2C%7B%22operation%22%3A%22output%22%2C%22format%22%3A%22webp%22%7D%5D](https://${PARAM:LOCATION}-${PARAM:PROJECT_ID}.cloudfunctions.net/ext-storage-image-processing-api-handler/process?operations=%5B%7B%22operation%22%3A%22input%22%2C%22type%22%3A%22url%22%2C%22url%22%3A%22https%3A%2F%2Fimages.unsplash.com%2Fphoto-1663659552548-25d7771802c9%3Fixlib%3Drb-1.2.1%26ixid%3DMnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8%26auto%3Dformat%26fit%3Dcrop%26w%3D774%26q%3D80%22%7D%2C%7B%22operation%22%3A%22grayscale%22%7D%2C%7B%22operation%22%3A%22output%22%2C%22format%22%3A%22webp%22%7D%5D)
+
+The result will be a grayscaled version of the image, in WebP format.
 
 ### Using the extension
 

extensions/storage-image-processing-api/PREINSTALL.md

@@ -1,12 +1,28 @@
 Use this extension to optimize and transform images via a powerful HTTP API with over 30 different image operations to enhance and manipulate your images.
 
-A cloud function called `process` will be added to your project which you can call from your code specifying:
-
-- The image to process
-- The operations to perform
-- The output image format
-
-The output image will be generated and cashed.
+This extension creates a Cloud Function named `process`, which can be called via a GET request, specifiying
+the operations to perform via the `operations` query parameter, for example:
+
+```js
+const operations = [
+  {
+    operation: 'input',
+    type: 'url',
+    url: 'https://example.com/image.jpg',
+  },
+  {
+    operation: 'grayscale',
+  },
+  {
+    operation: 'output',
+    format: 'webp',
+  },
+];
+
+const params = `?operations=${encodeURIComponent(JSON.stringify(operations))}`;
+```
+
+View the [official documentation](https://extensions.invertase.dev/storage-image-processing-api) for full usage examples.
 
 #### Additional setup
 

extensions/storage-image-processing-api/README.md

@@ -2,44 +2,80 @@
 
 **Author**: Invertase (**[https://invertase.io](https://invertase.io)**)
 
-**Description**: The Image Processing API allows you to process images in real-time.
+**Description**: Use this extension to optimize and transform images via a powerful HTTP API with over 30 different image operations to enhance and manipulate your images.
 
----
 
-### Console
 
-[![Install the Storage Image Processing API extension](https://github.com/FirebaseExtended/experimental-extensions/raw/next/install-extension.png?raw=true)](https://console.firebase.google.com/project/_/extensions/install?ref=invertase/storage-image-processing-api)
+**Details**: Use this extension to optimize and transform images via a powerful HTTP API with over 30 different image operations to enhance and manipulate your images.
 
-### Firebase CLI
+This extension creates a Cloud Function named `process`, which can be called via a GET request, specifiying
+the operations to perform via the `operations` query parameter, for example:
 
-```bash
-firebase ext:install invertase/storage-image-processing-api --project=projectId-or-alias
+```js
+const operations = [
+  {
+    operation: 'input',
+    type: 'url',
+    url: 'https://images.unsplash.com/photo-1663659552548-25d7771802c9?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=774&q=80',
+  },
+  {
+    operation: 'grayscale',
+  },
+  {
+    operation: 'output',
+    format: 'webp',
+  },
+];
+
+const params = `?operations=${encodeURIComponent(JSON.stringify(operations))}`;
 ```
 
-> Learn more about installing extensions in the Firebase Extensions documentation: [console](https://firebase.google.com/docs/extensions/install-extensions?platform=console), [CLI](https://firebase.google.com/docs/extensions/install-extensions?platform=cli)
+View the [official documentation](https://extensions.invertase.dev/storage-image-processing-api) for full usage examples.
+
+#### Additional setup
+
+Before installing this extension, make sure that you've [set up a Cloud Storage bucket](https://firebase.google.com/docs/storage) in your Firebase project.
+
+#### Billing
+
+To install an extension, your project must be on the [Blaze (pay as you go) plan](https://firebase.google.com/pricing)
+
+- You will be charged a small amount (typically around $0.01/month) for the Firebase resources required by this extension (even if it is not used).
+- This extension uses other Firebase and Google Cloud Platform services, which have associated charges if you exceed the service’s no-cost tier:
+  - Cloud Storage
+  - Cloud Functions (Node.js 10+ runtime. [See FAQs](https://firebase.google.com/support/faq#extensions-pricing))
+
+
 
----
 
 **Configuration Parameters:**
 
-- Cloud Functions location: Where do you want to deploy the functions created for this extension? You usually want a location close to your Storage bucket. For help selecting a location, refer to the [location selection guide](https://firebase.google.com/docs/functions/locations).
+* Cloud Functions location: Where do you want to deploy the functions created for this extension? You usually want a location close to your Storage bucket. For help selecting a location, refer to the [location selection guide](https://firebase.google.com/docs/functions/locations).
+
+* Cloud Storage bucket for images: The Cloud Storage bucket where images that are to be processed are located. API requests with input urls or paths that are not inside this bucket will be dropped.
+
+
+* Allowed CORS origins.: A comma delimited value of allowed CORS origins. Use the default of '*' to allow all origins. This is useful to lockdown your API and only allow your own website to embed the images directly. Note this will not prevent non-browser requests from accessing your API.
 
-- Cloud Storage bucket for images: The Cloud Storage bucket where images that are to be processed are located. API requests with input urls or paths that are not inside this bucket will be dropped.
 
-- Allowed CORS origins.: A comma delimited value of allowed CORS origins. Use the default of '\*' to allow all origins. This is useful to lockdown your API and only allow your own website to embed the images directly. Note this will not prevent non-browser requests from accessing your API.
 
-- Cloud Storage path where processed images will be cached.: A relative path in which to store cached images. For example, `cache`. If you prefer to store resized images at the default location, leave this field empty.
 
 **Cloud Functions:**
 
-- **api:** TODO
+* **handler:** Serves a API accepting incoming HTTP requests. 
+
+
 
 **APIs Used**:
 
-- storage-component.googleapis.com (Reason: Needed to use Cloud Storage)
+* storage-component.googleapis.com (Reason: Needed to use Cloud Storage)
+
+
 
 **Access Required**:
 
+
+
 This extension will operate with the following project IAM roles:
 
-- storage.admin (Reason: Allows the extension to store resized images in Cloud Storage)
+* storage.admin (Reason: Allows the extension to read images in Cloud Storage)

extensions/storage-image-processing-api/extension.yaml

@@ -3,7 +3,8 @@ version: 0.0.2
 specVersion: v1beta
 
 displayName: Image Processing API
-description: TODO
+description: >-
+  Use this extension to optimize and transform images via a powerful HTTP API with over 30 different image operations to enhance and manipulate your images.
 
 license: Apache-2.0
 
@@ -27,13 +28,13 @@ apis:
 
 roles:
   - role: storage.admin
-    reason: Allows the extension to store resized images in Cloud Storage
+    reason: Allows the extension to read images in Cloud Storage
 
 resources:
   - name: handler
     type: firebaseextensions.v1beta.function
     description: >-
-      TODO
+      Serves a API accepting incoming HTTP requests. 
     properties:
       location: ${param:LOCATION}
       runtime: nodejs14
@@ -118,12 +119,3 @@ params:
     example: '*.example.com,invertase.io'
     default: '*'
     required: true
-
-  - param: CACHED_IMAGES_PATH
-    label: Cloud Storage path where processed images will be cached.
-    description: >
-      A relative path in which to store cached images. For example,
-      `cache`. If you prefer to store resized images at the default
-      location, leave this field empty.
-    example: processed_images_cache
-    required: false

extensions/storage-image-processing-api/functions/src/index.ts

@@ -17,7 +17,7 @@
 import { AssertionError } from 'assert';
 import a2a from 'a2a';
 import cors from 'cors';
-import express, { Response } from 'express';
+import express, { Request, Response } from 'express';
 import * as firebase from 'firebase-admin';
 import * as functions from 'firebase-functions';
 import helmet from 'helmet';
@@ -168,7 +168,7 @@ app.get(
 // Express requires the function to have 4 arguments for a handler
 // to be treated as an error handler.
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
-app.use(function handleError(error, req, res, next) {
+app.use(function handleError(error: Error, req: Request, res: Response) {
   if (error instanceof StructError || error instanceof AssertionError) {
     functions.logger.warn(error.message, {
       url: req.url,