@based/client 2.5.1 → 2.6.0

package/dist/types.d.ts

@@ -0,0 +1,253 @@
+/// <reference types="node" />
+import type { GetOptions } from './selvaTypes/get';
+import type { SetOptions } from './selvaTypes/set';
+import type { Schema } from './selvaTypes/schema';
+import { Readable } from 'stream';
+export { GetOptions, SetOptions, Schema };
+export declare type DigestOptions = string;
+export declare enum RequestTypes {
+    Subscription = 1,
+    SubscriptionDiff = 2,
+    SendSubscriptionData = 3,
+    Unsubscribe = 4,
+    Set = 5,
+    Get = 6,
+    Configuration = 7,
+    GetConfiguration = 8,
+    Call = 9,
+    GetSubscription = 10,
+    Delete = 11,
+    Copy = 12,
+    Digest = 13,
+    Token = 14,
+    Track = 15,
+    Auth = 16
+}
+export declare enum AuthRequestTypes {
+    Login = 1,
+    Logout = 2,
+    RenewToken = 3
+}
+export declare type Configuration = {
+    schema: {
+        [db: string]: Schema;
+    };
+    dbs: string[];
+};
+export declare type Query = GetOptions;
+export declare type GenericObject = {
+    [key: string]: any;
+};
+export declare type Copy = {
+    $id: string;
+    db?: string;
+    deep?: boolean;
+    parents?: string[];
+    excludeFields?: string[];
+};
+export declare type ErrorObject = {
+    type: string;
+    message: string;
+    name?: string;
+    query?: GenericObject;
+    payload?: any;
+    auth?: boolean;
+    code?: string;
+};
+export declare type FunctionCallMessage = [RequestTypes.Call, string, number, any?];
+export declare type TrackMessage = [RequestTypes.Track, TrackPayload];
+export declare type RequestMessage<T = GenericObject> = [
+    (RequestTypes.Set | RequestTypes.Get | RequestTypes.Configuration | RequestTypes.GetConfiguration | RequestTypes.Delete | RequestTypes.Copy | RequestTypes.Digest),
+    number,
+    T
+];
+export declare type TokenMessage = [RequestTypes.Token, string?, boolean?];
+export declare type AuthMessage = [
+    RequestTypes.Auth,
+    AuthRequestTypes,
+    number,
+    GenericObject?
+];
+export declare type SubscribeMessage = [
+    RequestTypes.Subscription,
+    number,
+    GenericObject?,
+    number?,
+    (2 | 1 | 0)?,
+    string?
+];
+export declare type SendSubscriptionDataMessage = [
+    RequestTypes.SendSubscriptionData,
+    number,
+    number?
+];
+export declare type SendSubscriptionGetDataMessage = [
+    RequestTypes.GetSubscription,
+    number,
+    GenericObject?,
+    number?,
+    string?
+];
+export declare type UnsubscribeMessage = [
+    RequestTypes.Unsubscribe,
+    number
+];
+export declare type SubscriptionMessage = SubscribeMessage | SendSubscriptionDataMessage | UnsubscribeMessage | SendSubscriptionGetDataMessage;
+export declare type Message = RequestMessage | SubscriptionMessage | FunctionCallMessage | AuthMessage;
+export declare type SubscriptionDiffData = [
+    RequestTypes.SubscriptionDiff,
+    number,
+    GenericObject,
+    [
+        number,
+        number
+    ]
+];
+export declare type SubscriptionData = [
+    RequestTypes.Subscription,
+    number,
+    GenericObject,
+    number?,
+    ErrorObject?
+];
+export declare type RequestData = [
+    (RequestTypes.Set | RequestTypes.Get | RequestTypes.Configuration | RequestTypes.GetConfiguration | RequestTypes.Call | RequestTypes.Delete | RequestTypes.Copy | RequestTypes.Digest),
+    number,
+    any,
+    ErrorObject?
+];
+export declare type AuthorizedData = [RequestTypes.Token, number[], boolean?];
+export declare type AuthData = [
+    RequestTypes.Auth,
+    number,
+    GenericObject,
+    ErrorObject?
+];
+export declare type ResponseData = SubscriptionDiffData | SubscriptionData | RequestData | AuthorizedData | AuthData;
+export declare type TrackPayload = {
+    t: string;
+    u?: 1;
+    s?: 1;
+    e?: 1;
+    r?: 1;
+    o?: TrackOpts;
+};
+export declare type TrackOpts = {
+    amount?: number;
+};
+export declare type SendTokenOptions = {
+    isBasedUser?: boolean;
+    isApiKey?: boolean;
+    refreshToken?: string;
+};
+export declare type AnalyticsResult = {
+    all: {
+        total: number;
+        geo?: {
+            [isoCode: string]: number;
+        };
+    };
+    unique: {
+        total: number;
+        geo?: {
+            [isoCode: string]: number;
+        };
+    };
+    active: {
+        total: number;
+        max: number;
+        geo?: {
+            [isoCode: string]: number;
+        };
+    };
+};
+export declare type AnalyticsHistoryResult = {
+    all: {
+        total: [number, number][];
+        geo?: {
+            [isoCode: string]: [number, number][];
+        };
+    };
+    unique: {
+        total: [number, number][];
+        geo?: {
+            [isoCode: string]: [number, number][];
+        };
+    };
+    active: {
+        total: [number, number][];
+        geo?: {
+            [isoCode: string]: [number, number][];
+        };
+    };
+};
+export declare type AnalyticsTypes = string[];
+export declare type AnalyticsTypesOpts = {
+    type?: string;
+    $types: true;
+};
+export declare function isAnalyticsTypesOpts(opts: AnalyticsOpts | AnalyticsTypesOpts): opts is AnalyticsTypesOpts;
+export declare function isAnalyticsHistoryOpts(opts: AnalyticsOpts | AnalyticsTypesOpts): opts is AnalyticsHistoryOpts;
+export declare type AnalyticsOpts = {
+    type: string;
+    params?: {
+        [key: string]: number | string | boolean;
+    };
+    $geo?: string[] | boolean;
+};
+export declare type AnalyticsHistoryOpts = {
+    type: string;
+    params?: {
+        [key: string]: number | string | boolean;
+    };
+    $geo?: string[] | boolean;
+    $history: boolean | number;
+};
+export declare type LoginOpts = {
+    email: string;
+    password: string;
+};
+export declare type RenewTokenOpts = {
+    refreshToken: string;
+};
+export declare type FileUploadOptions = {
+    contents: Buffer | ArrayBuffer | string | File | Blob;
+    mimeType?: string;
+    name?: string;
+    url?: string | (() => Promise<string>);
+    id?: string;
+    raw?: boolean;
+    parents?: string[];
+    functionName?: string;
+};
+export declare type FileUploadStream = {
+    contents: Readable;
+    mimeType?: string;
+    extension?: string;
+    size: number;
+    name?: string;
+    url?: string | (() => Promise<string>);
+    id?: string;
+    raw?: boolean;
+    parents?: string[];
+    functionName?: string;
+};
+export declare type FileUploadPath = {
+    path: string;
+    mimeType?: string;
+    extension?: string;
+    name?: string;
+    url?: string | (() => Promise<string>);
+    id?: string;
+    raw?: boolean;
+    parents?: string[];
+    functionName?: string;
+};
+export declare type FileUploadSrc = {
+    src: string;
+    mimeType?: string;
+    name?: string;
+    id?: string;
+    parents?: string[];
+    size?: number;
+};

package/dist/types.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAnalyticsHistoryOpts = exports.isAnalyticsTypesOpts = exports.AuthRequestTypes = exports.RequestTypes = void 0;
+// eslint-disable-next-line
+var RequestTypes;
+(function (RequestTypes) {
+    // eslint-disable-next-line
+    RequestTypes[RequestTypes["Subscription"] = 1] = "Subscription";
+    // eslint-disable-next-line
+    RequestTypes[RequestTypes["SubscriptionDiff"] = 2] = "SubscriptionDiff";
+    // eslint-disable-next-line
+    RequestTypes[RequestTypes["SendSubscriptionData"] = 3] = "SendSubscriptionData";
+    // eslint-disable-next-line
+    RequestTypes[RequestTypes["Unsubscribe"] = 4] = "Unsubscribe";
+    // eslint-disable-next-line
+    RequestTypes[RequestTypes["Set"] = 5] = "Set";
+    // eslint-disable-next-line
+    RequestTypes[RequestTypes["Get"] = 6] = "Get";
+    // eslint-disable-next-line
+    RequestTypes[RequestTypes["Configuration"] = 7] = "Configuration";
+    // eslint-disable-next-line
+    RequestTypes[RequestTypes["GetConfiguration"] = 8] = "GetConfiguration";
+    // eslint-disable-next-line
+    RequestTypes[RequestTypes["Call"] = 9] = "Call";
+    // eslint-disable-next-line
+    RequestTypes[RequestTypes["GetSubscription"] = 10] = "GetSubscription";
+    // eslint-disable-next-line
+    RequestTypes[RequestTypes["Delete"] = 11] = "Delete";
+    // eslint-disable-next-line
+    RequestTypes[RequestTypes["Copy"] = 12] = "Copy";
+    // eslint-disable-next-line
+    RequestTypes[RequestTypes["Digest"] = 13] = "Digest";
+    // eslint-disable-next-line
+    RequestTypes[RequestTypes["Token"] = 14] = "Token";
+    // eslint-disable-next-line
+    RequestTypes[RequestTypes["Track"] = 15] = "Track";
+    // eslint-disable-next-line
+    RequestTypes[RequestTypes["Auth"] = 16] = "Auth";
+})(RequestTypes = exports.RequestTypes || (exports.RequestTypes = {}));
+var AuthRequestTypes;
+(function (AuthRequestTypes) {
+    // eslint-disable-next-line
+    AuthRequestTypes[AuthRequestTypes["Login"] = 1] = "Login";
+    // eslint-disable-next-line
+    AuthRequestTypes[AuthRequestTypes["Logout"] = 2] = "Logout";
+    // eslint-disable-next-line
+    AuthRequestTypes[AuthRequestTypes["RenewToken"] = 3] = "RenewToken";
+})(AuthRequestTypes = exports.AuthRequestTypes || (exports.AuthRequestTypes = {}));
+function isAnalyticsTypesOpts(opts) {
+    return opts.$types === true;
+}
+exports.isAnalyticsTypesOpts = isAnalyticsTypesOpts;
+function isAnalyticsHistoryOpts(opts) {
+    const hasHistory = opts.$history;
+    return !!hasHistory;
+}
+exports.isAnalyticsHistoryOpts = isAnalyticsHistoryOpts;
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";;;AASA,2BAA2B;AAC3B,IAAY,YAiCX;AAjCD,WAAY,YAAY;IACtB,2BAA2B;IAC3B,+DAAgB,CAAA;IAChB,2BAA2B;IAC3B,uEAAoB,CAAA;IACpB,2BAA2B;IAC3B,+EAAwB,CAAA;IACxB,2BAA2B;IAC3B,6DAAe,CAAA;IACf,2BAA2B;IAC3B,6CAAO,CAAA;IACP,2BAA2B;IAC3B,6CAAO,CAAA;IACP,2BAA2B;IAC3B,iEAAiB,CAAA;IACjB,2BAA2B;IAC3B,uEAAoB,CAAA;IACpB,2BAA2B;IAC3B,+CAAQ,CAAA;IACR,2BAA2B;IAC3B,sEAAoB,CAAA;IACpB,2BAA2B;IAC3B,oDAAW,CAAA;IACX,2BAA2B;IAC3B,gDAAS,CAAA;IACT,2BAA2B;IAC3B,oDAAW,CAAA;IACX,2BAA2B;IAC3B,kDAAU,CAAA;IACV,2BAA2B;IAC3B,kDAAU,CAAA;IACV,2BAA2B;IAC3B,gDAAS,CAAA;AACX,CAAC,EAjCW,YAAY,GAAZ,oBAAY,KAAZ,oBAAY,QAiCvB;AAED,IAAY,gBAOX;AAPD,WAAY,gBAAgB;IAC1B,2BAA2B;IAC3B,yDAAS,CAAA;IACT,2BAA2B;IAC3B,2DAAU,CAAA;IACV,2BAA2B;IAC3B,mEAAc,CAAA;AAChB,CAAC,EAPW,gBAAgB,GAAhB,wBAAgB,KAAhB,wBAAgB,QAO3B;AA2OD,SAAgB,oBAAoB,CAClC,IAAwC;IAExC,OAAQ,IAA2B,CAAC,MAAM,KAAK,IAAI,CAAA;AACrD,CAAC;AAJD,oDAIC;AAED,SAAgB,sBAAsB,CACpC,IAAwC;IAExC,MAAM,UAAU,GAAI,IAA6B,CAAC,QAAQ,CAAA;IAC1D,OAAO,CAAC,CAAC,UAAU,CAAA;AACrB,CAAC;AALD,wDAKC"}

package/docs/authorize.md

@@ -0,0 +1,56 @@
+# `Authorize` data function
+
+The authorize data function is a special function that serves as an authorization gatekeeper for the based queries and calls to data functions. It is run every time one is requested and blocks or allows access to the data.
+It works and has the same signature as normal data functions and should return a Promise with `true` or `false` boolean. 
+You can have your access logic here. For example, checking if the user is authenticated or if it matches whatever criteria you need for your application.
+
+example:
+```javascript
+export default async ({ based, user, payload, name, type, callstack}) => {
+	// ...
+	return true // or false
+}
+```
+
+### Exposed parameters
+
+| Parameter   | Description                                                                                                                                                                    |
+|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `based`     | Based client                                                                                                                                                                   |
+| `user`      | User object. Exposes token information about the user                                                                                                                          |
+| `payload`   | The query requested or the payload sent to the function                                                                                                                        |
+| `name`      | Name of the function. Empty in case of a query                                                                                                                                 |
+| `type`      | Type of call. `function` or `query` usually                                                                                                                                    |
+| `callstack` | Array with the names of the data function call stack. If one function calls another, the first function name will show in the callstack of the second function and so on. |
+
+
+## `user.token()`
+
+The `user` parameter exposes functionality to identify the user. If a user is authenticated, the based client will send an authorization token in the message. You can validate the token and decode it using the `user.token()`
+Will return `undefined` in case of an invalid token.
+
+Example:
+```javascript
+export default async ({ based, user, payload, name, type, callstack}) => {
+	// Leve this for now. Identifies a user as an UI user.
+	if (user.isBased) return true
+	
+	const token = user.token('publicKeySecret')
+	if (token.id) {
+		return true
+	}
+
+	return false
+}
+```
+
+## How to setup?
+The `authorize` function can be created directly on the Functions section of the Based UI or deployed using the CLI with the [`based deploy`](https://github.com/atelier-saulx/based/blob/main/packages/cli/README.md#deploy) command.
+It should be set as a non-observable function with the following config:
+
+```json
+{
+  "name": "authorize",
+  "observable": false
+}
+```

package/docs/files.md

@@ -0,0 +1,66 @@
+## Files
+
+Based provides a way to upload and serve user content without hassle using the `client.file()` API.  
+Assets uploaded through this tool are then served through a global CDN network, which allows for caching and fast content-delivery.
+
+An additional optimization step is executed when the user uploads a video or an image.
+Images are optimized and compressed, and served through an image specific CDN, while videos get transcoded to multiple resolutions, in HLS format.
+
+### Introduction
+
+Files can be uploaded using the Based client, which in addition to uploading the file, also sets a node of type `file` on the database, which can then be queried and referenced, like you would for any other node.
+
+This default type has several fields describing the file, including it's size, mime-type, timestamps for creation and update, progress status, and more. A crucial field is `src`, which contains a link that points to the file (through the appropriate CDN).
+
+> :exclamation: Video files will take longer to become available due to the transcoding process.
+
+### Usage
+
+#### Upload
+
+`client.file()` returns a promise that resolves with the new node's ID.
+
+```js
+import based from '@based/client'
+const client = based({
+  org: 'saulx',
+  project: 'test',
+  env: 'production',
+})
+
+const fileId = await client.file({
+  contents: 'This is a string I want to store as plain text!',
+  mimeType: 'text/plain',
+  name: 'my-file-name',
+})
+```
+
+The upload progress of the file can then be tracked by _observing_ the `progress` field of the resulting node.
+
+#### Accessing the file
+
+The file can be accessed by querying the database.
+
+```js
+const data = await client.get({
+  $id: fileId,
+  $all: true,
+})
+/*
+data = {
+  id: "fi6a535226",
+  name: "eb3f67a3bc65325bf739ebddd94403e5(1).png",
+  mimeType: "image/png",
+  version: "eb3f67a3bc65325bf739ebddd94403e5",
+  origin: "https://based-env-files-do-usproduction-enb-xz-apz--orn-t-v-...98446afcb87d.png",
+  src: "https://based-2129034536588.imgix.net/fi6a535226/84e62df3-75...98446afcb87d.png",
+  progress: 1,
+  size: 61901,
+  type: "file",
+  createdAt: 1650360875043,
+  updatedAt: 1650360882865,
+}
+*/
+```
+
+When using this API, one should always link to the file using the `src` field, since it's the one using the CDN. Pointing to the `origin` would lead to significantly higher data costs.

package/docs/get-started.md

@@ -0,0 +1,60 @@
+<div align="center">
+  <a href="javascript:void(0);" style="pointer-events: none;">
+        <img src="../../../.docs/assets/based-logo-black.svg#gh-light-mode-only" style="width: 350px; padding-bottom: 10px;" />
+        <img src="../../../.docs/assets/based.svg#gh-dark-mode-only" style="width: 350px; padding-bottom: 10px;" />
+
+  </a>
+</div>
+
+# Getting started
+
+The first step in getting started with using Based is creating a new project. To do so, after logging in, click the `+ New Project` button and type in a new project name.  
+Each project can have multiple environments (e.g. development and production).
+
+Go to the based [dashboard](https://based-website.vercel.app/dashboard)
+
+<!-- create-new-project video -->
+
+https://user-images.githubusercontent.com/16743760/164229679-0555beb5-4c56-4843-8fc6-266fa7f15ee4.mov
+
+In order to start adding data to the project, a **schema** is needed. The schema defines your data types, for examples the users of a chat app. To add a new type, click the `+ Create a new type` button.  
+Each type can have any number of fields that describe it, for example a user's email. These can be added in the schema editor using the `+ Add Type` button.
+
+<!-- add-user-type-to-schema video-->
+
+https://user-images.githubusercontent.com/16743760/164229696-83de5222-2d8c-4778-8769-a0c3eea1f239.mov
+
+Next, it's time to add some content! This can be done through the Dashboard using the built-in content editor.
+
+<!-- add-content video -->
+
+https://user-images.githubusercontent.com/16743760/164229707-bc9652a2-0823-44b7-825d-1efdcc080ce6.mov
+
+Once the environment is up and running, it is time to jump into the code side of things.
+
+```js
+import based from '@based/client'
+
+const client = based({
+  org: 'my-org',
+  project: 'chat',
+  env: 'production',
+})
+
+// observe some data
+await client.observe(
+  { $id: 'root', children: { $all: true, $list: true } },
+  (data) => {
+    console.log(data)
+  }
+)
+
+// set data
+await client.set({
+  type: 'user',
+  email: 'francesco@example.com',
+  favoriteThing: 'pizza',
+})
+```
+
+> [Click here to read more about the Javascript Based SDK](../README.md)