Merge branch 'main' of github.com-mateuszmlc:polybase/docs into eng-363-allow-array-collection-type-delegates

Author: mateuszmlc

api-reference/call-function.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Call a function"
-api: "POST https://testnet.polybase.xyz/v0/collections/<collection_path>/records/<record_id>/call/<function_name>"
+api: "POST https://testnet.polybase.xyz/v0/collections/{collection_path}/records/{record_id}/call/{function_name}"
 ---
 
 <RequestExample>
@@ -9,6 +9,9 @@ api: "POST https://testnet.polybase.xyz/v0/collections/<collection_path>/records
 curl --request POST \
      --url https://testnet.polybase.xyz/v0/collections/polybase%2Fcore%2Fusers/records/id123/call/functionName\
      --header 'Accept: application/json'
+     -d '{ "args": ["Polybase"] }' 
+     # optional (if supplied ctx.publicKey will be populated)
+     --header 'X-Polybase-Signature: v=0,t=1671884992,h=eth-personal-sign,sig=0x288db6271d92253ae19983a8e5110f1bc1bef1911210127ccbf657d85428ba9917aa9457f0f8e7f300a36b106525d3a3471e63ae265af4898742040a377e1da11c'
 ```
 
 </RequestExample>
@@ -32,4 +35,32 @@ curl --request POST \
 
 <ParamField body="args" type="array" required>
   An array of arguments that should be passed to the the function being called on the collection, as defined in the collection schema.
+
+  For example, if the collection schema is as follows:
+
+  ```js
+    collection Users {
+      id: string;
+      name: string;
+
+      constructor (name: string) {
+        this.id = PublicKey;
+        this.name = name;
+      }
+
+      setName(name: string) {
+        this.name = name;
+      }
+    }
+  ```
+
+  The args would be:
+  ```json
+  {
+    args: [
+      // This is the 1st parameter name: string
+      "Polybase"
+    ]
+  }
+  ```
 </ParamField>

api-reference/create-record.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Create a record"
-api: "POST https://testnet.polybase.xyz/v0/collections/<collection_path>/records"
+api: "POST https://testnet.polybase.xyz/v0/collections/{collection_path}/records"
 ---
 
 <RequestExample>
@@ -9,6 +9,9 @@ api: "POST https://testnet.polybase.xyz/v0/collections/<collection_path>/records
 curl --request POST \
      --url https://testnet.polybase.xyz/v0/collections/polybase%2Fcore%2Fusers/records\
      --header 'Accept: application/json'
+     -d '{ "args": ["Polybase"] }' 
+     # optional (if supplied ctx.publicKey will be populated)
+     --header 'X-Polybase-Signature: v=0,t=1671884992,h=eth-personal-sign,sig=0x288db6271d92253ae19983a8e5110f1bc1bef1911210127ccbf657d85428ba9917aa9457f0f8e7f300a36b106525d3a3471e63ae265af4898742040a377e1da11c'
 ```
 
 </RequestExample>
@@ -22,5 +25,31 @@ curl --request POST \
 ## Body Params
 
 <ParamField body="args" type="array" required>
-  An array of arguments that should be passed to the the constructor of the collection, as defined in the collection schema.
+  An array of arguments that should be passed to the the `constructor` of the collection, as defined in the collection schema. For example, if the collection schema is as follows:
+
+  ```js
+    collection Users {
+      id: string;
+      name: string;
+      age: number;
+
+      constructor (name: string, age: number) {
+        this.id = PublicKey;
+        this.name = name;
+        this.age = age;
+      }
+    }
+  ```
+
+  The args would be:
+  ```json
+  {
+    args: [
+      // This is the 1st parameter name: string
+      "Polybase",
+      // This is the 2nd parameter age: number
+      1
+    ]
+  }
+  ```
 </ParamField>

api-reference/get-record.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Get record"
-api: "GET https://testnet.polybase.xyz/v0/collections/<collection_path>/records/<record_id>"
+api: "GET https://testnet.polybase.xyz/v0/collections/{collection_path}/records/<record_id>"
 ---
 
 <RequestExample>

api-reference/list-records.mdx

@@ -1,6 +1,6 @@
 ---
 title: "List records"
-api: "GET https://testnet.polybase.xyz/v0/collections/<collection_path>/records"
+api: "GET https://testnet.polybase.xyz/v0/collections/{collection_path}/records"
 ---
 
 <RequestExample>

api-reference/overview.mdx

@@ -15,9 +15,10 @@ The Polybase Gatweay API uses public/private key pair for authentication. That m
 Authentication is composed of:
 
  - `v` the version being used, should be `v=0` 
- - `t` current unix timestamp in seconds
+ - `t` current unix timestamp in milliseconds
  - `h` type of hash signing being used `eth-personal-sign` is currently the only allowed option
- - `sig` the signature of the data 
+ - `sig` the signature of the data (see below)
+ - `pk` **optional** 65 byte public key (secp256k1 algorithm)
 
 
 An example of a valid authroization:
@@ -26,4 +27,24 @@ An example of a valid authroization:
 v=0,t=1671884992,h=eth-personal-sign,sig=0x288db6271d92253ae19983a8e5110f1bc1bef1911210127ccbf657d85428ba9917aa9457f0f8e7f300a36b106525d3a3471e63ae265af4898742040a377e1da11c
 ```
 
-The token is passed in the `X-Polybase-Signature` header of the request.
+The token is passed in the `X-Polybase-Signature` header of the request.
+
+
+### Signature (`sig`)
+
+To generate `sig` you must sign a string in the format `<timestamp>.<body_json>`. Where `timestamp` is the `t` you provided above, and `body_json` is the body of the request (as a JSON string).
+
+You can use the [@polybase/util](https://www.npmjs.com/package/@polybase/util) package to generate the signature from any 32 bytes private key, and the sign function to create the signature.
+
+```typescript
+import { secp256k1 } from '@polybase/util'
+
+// You can use any 32 byte private key from any library, 
+// here is an example from @polybase/util
+let private_key = secp256k1.generatePrivateKey();
+
+function createSig (timestamp, body) {
+  const str_to_sign = `${timestamp}.${JSON.stringify(body)}`;
+  return secp256k1.sign(privateKey, str_to_sign);
+}
+```

changelog.mdx

@@ -18,13 +18,37 @@ breaking changes.
   - Array can be of Collection type
   - Array of Collection type can be used with read/call/delegate directives
 
+## \[0.3.26] - 2023-03-07
+
+### Fixed
+
+  - Fixed "Failed to fetch metadata" in the explorer
+  
+### Changed
+
+  - The polybase-ts client libraries are now natively web-compatible
+
 ## \[0.3.23\] - 2023-01-26
 
 ### Fixed
 
   - Fixed invalid dependencies in CDN bundles
 
 
+## \[0.3.23\] - 2023-01-21
+
+### Added
+
+  - Authorization rules using `@public`, `@read`, `@call` and `@delegate`
+
+
+## \[0.3.23\] - 2023-01-21
+
+### Added
+
+  - New collection interface AST that is now stored in the database. Clients do not need to parse collection code anymore
+
+
 ## \[0.3.22\] - 2023-01-17
 
 ### Added

collections.mdx

@@ -41,17 +41,19 @@ db.signer((data) => {
 })
 
 const createResponse = await db.applySchema(`
+  @public
   collection CollectionName {
     id: string;
     country?: string;
-    publicKey?: string;
+    publicKey?: PublicKey;
 
     constructor (id: string, country: string) {
       this.id = id;
       this.country = country;
 
       // Assign the public key of the user making the request to this record
-      this.publicKey = ctx.publicKey;
+      if (ctx.publicKey)
+        this.publicKey = ctx.publicKey;
     }
   }
 `, 'your-namespace') // your-namespace is optional if you have defined a default namespace
@@ -76,6 +78,7 @@ indexes for your collection records. The following is a valid collection
 definition.
 
 ```js
+@public
 collection CollectionName {
   id: string;
   name?: string;
@@ -107,6 +110,7 @@ at the top most part of your collection. A collection should always have a `id`
 field (`id` is unique). By default, all fields are required.
 
 ```js
+@public
 collection CollectionName {
   id: string;
   age: number;
@@ -137,6 +141,7 @@ All fields are required by default, if you want to make a field optional simply
 append `?` after the field name and before the `:`. For example:
 
 ```js
+@public
 collection CollectionName {
   id: string;
   required: number;
@@ -151,14 +156,15 @@ collection CollectionName {
 Field values can only be modified using functions.
 
 ```js
+@public
 collection Account {
   id: string;
   name: string;
   balance: number;
-  publicKey: string;
+  publicKey: PublicKey;
 
   constructor (name: string) {
-    this.id = ctx.publicKey;
+    this.id = ctx.publicKey.toHex();
     this.name = name;
     this.publicKey = ctx.publicKey;
     this.balance = 0;
@@ -223,11 +229,12 @@ it against the records own `publicKey`:
 collection CollectionName {
   id: string;
   name?: string;
-  publicKey?: string;
+  publicKey?: PublicKey;
 
   constructor (id: string) {
     this.id = id;
-    this.publicKey = ctx.publicKey;
+    if (ctx.publicKey)
+      this.publicKey = ctx.publicKey;
   }
 
   setName (name: string) {
@@ -260,6 +267,7 @@ const records = await collectionReference
 You would need the following schema:
 
 ```js
+@public
 collection cities {
   name: string;
   country: string;
@@ -284,6 +292,7 @@ const records = await collectionReference
 You would need the following schema:
 
 ```js
+@public
 collection cities {
   name: string;
   country: string;
@@ -293,6 +302,64 @@ collection cities {
 }
 ```
 
+## Authorization
+
+By default, collections in Polybase are private and their records cannot be accessed.
+To make a collection private, remove the `@public` directive.
+
+To allow users to access and manipulate their records, you can use the following directives:
+
+### `@read`
+
+Allows anyone who can sign using the specified public key to read the record.
+
+```js
+collection Response {
+  @read
+  publicKey: PublicKey;
+  ...
+}
+```
+
+### `@call`
+
+Allows anyone who can sign using the specified public key to call a given function.
+
+```js
+collection Form {
+  @read
+  creator: PublicKey;
+
+  @call(creator);
+  update ()  {
+    ...
+  }
+}
+```
+
+### `@delegate`
+
+Allows anyone who can sign using the specified public key to read the response data, via delegated permissions.
+
+Example of delegating `Response` → `Form` → `User` → `publicKey`:
+
+```js
+collection Response {
+  @read
+  form: Form;
+}
+
+collection Form {
+  @delegate
+  creator: User;
+}
+
+collection User {
+  @delegate
+  publicKey: PublicKey;
+}
+```
+
 ## Reference a collection
 
 To reference a collection, you can call `.collection("collection-name")` on your

delete-data.mdx

@@ -10,13 +10,14 @@ The following provides an example of a delete function that only allows the
 owner of the record to delete it.
 
 ```js
+@public
 collection Place {
   country: string;
   owner: id;
 
   constructor (id: string) {
     this.id = id;
-    this.owner = this.ctx.publicKey;
+    this.owner = ctx.publicKey.toHex();
   }
 
   del () {

get-started.mdx

@@ -62,6 +62,7 @@ In this example we use the JavaScript SDK to create a collection called `City` t
 
 ```js
 await db.applySchema(`
+  @public
   collection City {
     id: string;
     name: string;