feat: add prev caveat to store/list and upload/list

Per storacha/w3ui#143 we'd like to give
clients a way to get the previous page of results rather than the next
page.

This change introduces a `prev` caveat which, when set to true, will
return the page of results preceding `cursor`.

I considered calling this `reverse` or `rev` but I think that implies
that results will be returned sorted in reverse, which is not
the intent.

packages/capabilities/src/store.js

@@ -150,6 +150,10 @@ export const list = base.derive({
        * Maximum number of items per page.
        */
       size: Schema.integer().optional(),
+      /**
+       * If true, return page of results preceding cursor. Defaults to false.
+       */
+      prev: Schema.boolean().optional(),
     },
     derives: (claimed, delegated) => {
       if (claimed.with !== delegated.with) {

packages/capabilities/src/upload.js

@@ -150,6 +150,10 @@ export const list = base.derive({
        * Maximum number of items per page.
        */
       size: Schema.integer().optional(),
+      /**
+       * If true, return page of results preceding cursor. Defaults to false.
+       */
+      prev: Schema.boolean().optional(),
     },
   }),
   /**

packages/upload-client/src/store.js

@@ -136,6 +136,7 @@ export async function list(
       nb: {
         cursor: options.cursor,
         size: options.size,
+        prev: options.prev,
       },
     })
     .execute(conn)

packages/upload-client/src/types.ts

@@ -174,6 +174,10 @@ export interface Pageable {
    * Maximum number of items to return.
    */
   size?: number
+  /**
+   * If true, return page of results preceding cursor. Defaults to false.
+   */
+  prev?: boolean
 }
 
 export interface RequestOptions extends Retryable, Abortable, Connectable {}

packages/upload-client/src/upload.js

@@ -99,6 +99,7 @@ export async function list(
       nb: {
         cursor: options.cursor,
         size: options.size,
+        prev: options.prev,
       },
     })
     .execute(conn)

spec/capabilities.md

@@ -199,13 +199,16 @@ The `with` field of the invocation must be set to the DID of the memory space to
 
 `cursor` can be set to start listing from an item in the middle of the list. Its value should be a `cursor` returned by a previous invocation of `store/list`
 `size` can be set to change the number of items returned by an `store/list` invocation
+`prev` can be set to `true` to return the page of results preceding `cursor` rather than the results after `cursor`. Defaults to `false`.
+
 
 Taken together, the CARs in the `shards` array should contain all the blocks in the DAG identified by the `root` CID.
 
 | field       | value                    | required? | context                                                         |
 | ----------- | ------------------------ | --------- | --------------------------------------------------------------- |
 | `nb.cursor` | string                   | ❌         | A cursor returned by a previous invocation                      |
 | `nb.size`   | integer                  | ❌         | The maximum number of results to return                         |
+| `nb.prev`   | boolean                  | ❌         | If true, return previous page of results                        |
 
 ## `upload/` namespace
 
@@ -288,13 +291,15 @@ The `with` field of the invocation must be set to the DID of the memory space to
 
 `cursor` can be set to start listing from an item in the middle of the list. Its value should be a `cursor` returned by a previous invocation of `upload/list`
 `size` can be set to change the number of items returned by an `upload/list` invocation
+`prev` can be set to `true` to return the page of results preceding `cursor` rather than the results after `cursor`. Defaults to `false`.
 
 Taken together, the CARs in the `shards` array should contain all the blocks in the DAG identified by the `root` CID.
 
 | field       | value                    | required? | context                                                         |
 | ----------- | ------------------------ | --------- | --------------------------------------------------------------- |
 | `nb.cursor` | string                   | ❌         | A cursor returned by a previous invocation                      |
 | `nb.size`   | integer                  | ❌         | The maximum number of results to return                         |
+| `nb.prev`   | boolean                  | ❌         | If true, return previous page of results                        |
 ## `voucher/` namespace
 
 TODO: more voucher docs when implementation details settle down a bit.