@dittolive/ditto 4.6.0 → 4.7.0-rc.3

package/types/ditto.d.ts

@@ -521,7 +521,7 @@ type Pointer<Type> = {
 /** @internal */
 declare const DittoCRDTTypeKey = "_ditto_internal_type_jkb12973t4b";
 /** @internal */
-type FFIDqlResponse = 'dittoffi_query_result_t';
+type FFIQueryResult = 'dittoffi_query_result_t';
 /** @internal */
 type FFIWriteTransaction = 'CWriteTransaction_t';
 /** @internal */
@@ -2069,7 +2069,7 @@ declare class QueryResult {
      */
     mutatedDocumentIDs(): DocumentID[];
     /** @internal */
-    constructor(responsePointer: Pointer<FFIDqlResponse>);
+    constructor(queryResultPointer: Pointer<FFIQueryResult>);
 }
 
 /**
@@ -2813,6 +2813,100 @@ declare class Store {
     registerLiveQueryWebhook(collectionName: string, query: string, url: string): Promise<DocumentID>;
 }
 
+/**
+ * Indicates whether a connection request should be authorized.
+ *
+ * `allow` if the request should be authorized, `deny` otherwise.
+ */
+type ConnectionRequestAuthorization = 'allow' | 'deny';
+/**
+ * A handler for connection requests from other peers.
+ *
+ * Set a `ConnectionRequestHandler` on
+ * {@link Presence.connectionRequestHandler | `ditto.presence.connectionRequestHandler`}
+ * to allow or deny connection requests from other peers.
+ *
+ * @param connectionRequest - Contains information about the remote peer that
+ *   can be used to make an authorization decision.
+ *
+ * @returns `allow` if the request should be authorized, `deny` otherwise.
+ *
+ * @see
+ * {@link Presence.connectionRequestHandler | `ditto.presence.connectionRequestHandler`}
+ * for details on the connection request API.
+ */
+type ConnectionRequestHandler = (connectionRequest: ConnectionRequest) => Promise<ConnectionRequestAuthorization>;
+/**
+ * Contains information about a remote peer that has requested a connection.
+ *
+ * Connection requests and their authorization are scoped to a specific Ditto
+ * peer and connection type.
+ */
+declare class ConnectionRequest {
+    /**
+     * The unique peer key of the remote peer.
+     *
+     * @see field `peerKeyString` on {@link Peer} for more information on peer
+     * keys.
+     */
+    get peerKeyString(): string;
+    /**
+     * Metadata associated with the remote peer.
+     *
+     * This is an empty object if the remote peer has not set any metadata.
+     *
+     * Set peer metadata for the local peer using {@link Presence.peerMetadata}
+     * or {@link Presence.peerMetadataJSONString}.
+     *
+     * This is a convenience property that wraps
+     * {@link peerMetadataJSONString | `peerMetadataJSONString()`}.
+     */
+    get peerMetadata(): Record<string, any>;
+    /**
+     * JSON-encoded metadata associated with the remote peer.
+     *
+     * This is a JSON string representing an empty dictionary if the remote peer
+     * has not set any metadata.
+     *
+     * Set peer metadata for the local peer using {@link Presence.peerMetadata} or
+     * {@link Presence.peerMetadataJSONString}.
+     *
+     * Uses UTF-8 encoding.
+     */
+    get peerMetadataJSONString(): string;
+    /**
+     * Metadata for the remote peer that is provided by the identity service.
+     *
+     * Use an authentication webhook to set this value. See Ditto's online
+     * documentation for more information on how to configure an authentication
+     * webhook.
+     *
+     * Convenience property that wraps {@link identityServiceMetadataJSONString}.
+     */
+    get identityServiceMetadata(): Record<string, any>;
+    /**
+     * JSON-encoded metadata for the remote peer that is provided by the
+     * identity service.
+     *
+     * Use an authentication webhook to set this value. See Ditto's online
+     * documentation for more information on how to configure an authentication
+     * webhook.
+     *
+     * Uses UTF-8 encoding.
+     */
+    get identityServiceMetadataJSONString(): string;
+    /**
+     * The network transport of this connection request.
+     *
+     * Expect to receive separate connection requests for each network
+     * transport that connects the local and remote peer.
+     */
+    get connectionType(): ConnectionType;
+    /** @internal */
+    toString(): string;
+    private deref;
+}
+
 /** Types of connections that can be established between two peers. */
 type ConnectionType = 'P2PWiFi' | 'WebSocket' | 'AccessPoint' | 'Bluetooth';
 /**
@@ -2874,8 +2968,36 @@ type Peer = {
      *
      * NOTE: This will be be empty when a peer is not updated to the latest
      * version of the SDK.
+     *
+     * @deprecated Use {@link peerKeyString} instead.
      */
     peerKey: Uint8Array;
+    /**
+     * The peer key is a unique identifier for a given peer, equal to or
+     * derived from the cryptographic public key used to authenticate it.
+     *
+     * NOTE: This will be be empty when a peer is not updated to the latest
+     * version of the SDK.
+     */
+    peerKeyString: string;
+    /**
+     * Metadata associated with the peer, empty dictionary by default.
+     *
+     * Use `ditto.presence.setPeerMetadata()` or
+     * `ditto.presence.setPeerMetadataJSONData()` to set this value.
+     *
+     * @see {@link Presence.peerMetadata | `ditto.presence.peerMetadata`} for
+     * details on usage of metadata.
+     */
+    peerMetadata: Record<string, any>;
+    /**
+     * Metadata associated with the peer by the identity service.
+     *
+     * Use an authentication webhook to set this value. See Ditto's online
+     * documentation for more information on how to configure an authentication
+     * webhook.
+     */
+    identityServiceMetadata: Record<string, any>;
     /**
      * The human-readable device name of the peer. This defaults to the hostname
      * but can be manually set by the application developer of the other peer.
@@ -2930,11 +3052,95 @@ type PresenceGraph = {
 declare class Presence {
     /** The Ditto instance this object belongs to. */
     readonly ditto: Ditto;
+    /**
+     * Set this handler to control which peers in a Ditto mesh can connect to the
+     * current peer.
+     *
+     * Each peer in a Ditto mesh will attempt to connect to other peers that it
+     * can reach. By default, the mesh will try and establish connections that
+     * optimize for the best overall connectivity between peers. However, you can
+     * set this handler to assert some control over which peers you connect to.
+     *
+     * If set, this handler is called for every incoming connection request from a
+     * remote peer and is passed the other peer's `peerKey`, `peerMetadata`, and
+     * `identityServiceMetadata`. The handler can then accept or reject the
+     * request by returning an according {@link ConnectionRequestAuthorization}
+     * value. When the connection request is rejected, the remote peer may retry
+     * the connection request after a short delay.
+     *
+     * Connection request handlers must reliably respond to requests within a
+     * short time. If a handler takes too long to respond or throws an exception,
+     * the connection request will be denied. The response timeout is currently 10
+     * seconds but may be subject to change in future releases.
+     *
+     * @see {@link peerMetadata | peerMetadata()}
+     */
+    get connectionRequestHandler(): ConnectionRequestHandler | null;
+    /**
+     * @throws TypeError: if the given handler is not a function.
+     */
+    set connectionRequestHandler(handler: ConnectionRequestHandler | null);
     /**
      * Returns the current presence graph capturing all known peers and
      * connections between them.
      */
     get graph(): PresenceGraph;
+    /**
+     * Metadata associated with the current peer. Other peers in the same mesh can
+     * access this user-provided object of metadata via the presence {@link graph}
+     * and when evaluating connection requests using
+     * {@link connectionRequestHandler | connectionRequestHandler()}.
+     *
+     * Uses UTF-8 encoding.
+     *
+     * @see {@link peerMetadata | peerMetadata()} for a convenience property that
+     * provides access to parsed metadata.
+     */
+    get peerMetadataJSONString(): string;
+    /**
+     * Set arbitrary metadata to be associated with the current peer.
+     *
+     * The metadata must not exceed 4 KB in size when JSON-encoded.
+     *
+     * @param {string} jsonString: JSON-encoded metadata.
+     *
+     * @throws {@link DittoError} `validation/invalid-json`: if `jsonString` does
+     * not contain valid JSON.
+     *
+     * @throws {@link DittoError} `validation/not-an-object`: if `jsonString` does
+     * not contain an object.
+     *
+     * @throws {@link DittoError} `validation/size-limit-exceeded`: if the size
+     *  limit for `jsonString` has been exceeded.
+     *
+     * @see {@link peerMetadataJSONString | peerMetadataJSONString()} for details
+     * on usage of metadata.
+     */
+    setPeerMetadataJSONString(jsonString: string): Promise<void>;
+    /**
+     * This is a convenience property that wraps
+     * {@link peerMetadataJSONString | peerMetadataJSONString()}.
+     *
+     * @see {@link peerMetadataJSONString | peerMetadataJSONString()} for details.
+     */
+    get peerMetadata(): Record<string, any>;
+    /**
+     * This is a convenience method that wraps
+     * {@link setPeerMetadataJSONString | setPeerMetadataJSONString()}.
+     *
+     * @throws {@link DittoError} `validation/not-an-object`: if `peerMetadata` is
+     * not an object.
+     *
+     * @throws {@link DittoError} `validation/not-json-compatible`: if
+     * `peerMetadata` is not JSON serializable.
+     *
+     * @throws {@link DittoError} `validation/size-limit-exceeded`: if the size
+     *  limit for `peerMetadata` has been exceeded.
+     *
+     * @see {@link setPeerMetadataJSONString | setPeerMetadataJSONString()} for
+     * details.
+     */
+    setPeerMetadata(peerMetadata: Record<string, any>): Promise<void>;
     /**
      * Request information about Ditto peers in range of this device.
      *
@@ -2949,6 +3155,7 @@ declare class Presence {
     /** @internal */
     close(): void;
     private observerManager;
+    private _connectionRequestHandler;
 }
 
 /**
@@ -3293,7 +3500,7 @@ declare class SmallPeerInfo {
      *
      * - Must be a JSON object (not an array, string, number, etc.)
      * - The size when encoded as JSON must be less than 128 KB
-     * - May only be nested up to 2 levels deep
+     * - May only be nested up to 64 levels deep
      *
      * @example <caption>Valid metadata</caption>
      * ditto.smallPeerInfo.metadata = {
@@ -3303,17 +3510,6 @@ declare class SmallPeerInfo {
      *   }
      * }
      *
-     * @example <caption>Invalid metadata</caption>
-     * // This is invalid and results in an error.
-     * ditto.smallPeerInfo.metadata = {
-     *   "foo": "bar",
-     *   "nested": {
-     *     "illegal": {
-     *       "inner": "value"
-     *     }
-     *   }
-     * }
-     *
      * @throws when set to a value that violates any of the constraints listed
      * above.
      */
@@ -3382,15 +3578,19 @@ declare class Ditto {
      */
     static get VERSION(): string;
     /**
-     * Configure a custom identifier for the current device.
+     * Configure a custom identifier for this peer.
+     *
+     * When using {@link Presence.observe | presence.observe()}, each remote peer
+     * is represented by a short UTF-8 "device name". By default this will be a
+     * truncated version of the device's hostname.
      *
-     * When using {@link Presence.observe | presence.observe()}, each remote peer is
-     * represented by a short UTF-8 "device name". By default this will be a
-     * truncated version of the device's hostname. It does not need to be unique
-     * among peers. Configure the device name before calling
-     * {@link startSync | startSync()}. If it is too long it may be truncated.
+     * Changes to this property after {@link startSync | startSync()} was called
+     * will only take effect after the next restart of sync. The value does not
+     * need to be unique among peers. Device names longer than 24 bytes will be
+     * truncated once {@link startSync | startSync()} is called.
      */
-    deviceName: string;
+    get deviceName(): string;
+    set deviceName(value: string);
     /** Returns a string identifying the version of the Ditto SDK. */
     get sdkVersion(): string;
     /**
@@ -3543,8 +3743,6 @@ declare class Ditto {
      *
      * @param licenseToken the license token to activate the `Ditto` instance
      * with. You can find yours on the [Ditto portal](https://portal.ditto.live).
-     *
-     * @throws {Error} if called in a React Native environment.
      */
     setOfflineOnlyLicenseToken(licenseToken: string): void;
     /**
@@ -3709,6 +3907,7 @@ declare class Ditto {
     private _isActivated;
     private _isSyncActive;
     private _isClosed;
+    private _deviceName;
     /** Set of pending operations that need to complete before the Ditto instance can be closed in a safe manner. */
     private pendingOperations;
     private authClientValidityChanged;
@@ -3993,9 +4192,9 @@ type ErrorCode = keyof typeof ERROR_CODES;
  */
 declare const ERROR_CODES: {
     /** Internal error for unexpected system states */
-    readonly internal: "An unexpected internal error occured. Please get in touch with Ditto customer service to report this incident.";
-    /** Internal error with an unknown error cause **/
-    readonly 'internal/unknown-error': "An unexpected internal error occured. Please get in touch with Ditto customer service to report this incident.";
+    readonly internal: "An unexpected internal error occurred. Please get in touch with Ditto customer service to report this incident.";
+    /** Internal error with an unknown error cause */
+    readonly 'internal/unknown-error': "An unexpected internal error occurred. Please get in touch with Ditto customer service to report this incident.";
     /** Error when using a feature not supported by the current environment */
     readonly 'sdk/unsupported': "The feature is not supported by the current environment.";
     /** Error for invalid DQL query arguments. */
@@ -4026,14 +4225,36 @@ declare const ERROR_CODES: {
     readonly 'store/failed-to-create-attachment': "The attachment could not be created.";
     /** An unclassified error while fetching an attachment. */
     readonly 'store/failed-to-fetch-attachment': "The attachment could not be fetched.";
+    /** An error representing an invalid license token. */
+    readonly 'activation/license-token-verification-failed': "Please provide a valid license token.";
+    /** An error representing an expired license token.  */
+    readonly 'activation/license-token-expired': "The license token expired. Please renew it.";
+    /** An error representing a token is in an unsupported future format. */
+    readonly 'activation/license-token-unsupported-future-version': "The provided license token is in an unsupported future format.";
+    /** The operation failed because it requires an activated Ditto instance. */
+    readonly 'activation/not-activated': "The operation failed because the Ditto instance has not yet been activated.";
+    /** A validation error where the maximum depth limit was exceeded. */
+    readonly 'validation/depth-limit-exceeded': "The maximum depth limit has been exceeded.";
+    /** A validation error where the value is not valid CBOR. */
+    readonly 'validation/invalid-cbor': "The value provided is not valid CBOR.";
+    /** A validation error where the value is not valid JSON. */
+    readonly 'validation/invalid-json': "The value provided is not valid JSON.";
+    /** A validation error where a value is required to be a JavaScript object */
+    readonly 'validation/not-an-object': "The value provided is not of type object.";
+    /** The value provided can not be serialized as JSON. */
+    readonly 'validation/not-json-compatible': "Value is not serializable as JSON.";
+    /** A validation error where a size limit was exceeded. */
+    readonly 'validation/size-limit-exceeded': "The size limit has been exceeded.";
 };
 
 /**
  * Error codes for FFI result.
  *
+ * This should include all variants of `FfiError` in `ffi/src/result/error.rs`.
+ *
  * @internal
  */
-type FFIResultErrorCode = 'StoreDocumentNotFound' | 'StoreDatabase' | 'StoreQuery' | 'Crdt' | 'JsFloatingStoreOperation' | 'DqlQueryCompilation' | 'DqlInvalidQueryArgs' | 'DqlUnsupported' | 'Base64Invalid';
+type FFIResultErrorCode = 'ActivationLicenseTokenExpired' | 'ActivationLicenseTokenInvalid' | 'ActivationLicenseUnsupportedFutureVersion' | 'ActivationNotActivated' | 'Base64Invalid' | 'Crdt' | 'DqlInvalidQueryArgs' | 'DqlQueryCompilation' | 'DqlUnsupported' | 'JsFloatingStoreOperation' | 'StoreDatabase' | 'StoreDocumentNotFound' | 'StoreQuery' | 'ValidationDepthLimitExceeded' | 'ValidationInvalidCbor' | 'ValidationInvalidJson' | 'ValidationNotAMap' | 'ValidationSizeLimitExceeded';
 /**
  * Represents an exception that occurred during a call into the Ditto FFI.
  *
@@ -4082,6 +4303,22 @@ type ErrorContext = Record<string, any>;
  *
  * Please reference {@link ERROR_CODES} for a comprehensive list of
  * possible error codes in this SDK version.
+ *
+ * @example
+ * Handling a specific error code:
+ * ```typescript
+ * import { Attachment, DittoError } from '@dittolive/ditto'
+ *
+ * let attachment: Attachment
+ * try {
+ *   attachment = await ditto.store.newAttachment(filePath)
+ * } catch (error) {
+ *   if (error instanceof DittoError && error.code === 'store/attachment-file-not-found') {
+ *     // Handle a non-existing file
+ *   }
+ *   throw error // Rethrow any other error
+ * }
+ * ```
  */
 declare class DittoError extends Error {
     /**
@@ -4210,5 +4447,5 @@ declare class CBOR {
     static decode(data: Uint8Array, reviver?: (key: any, value: any) => any): any;
 }
 
-export { type Address, Attachment, type AttachmentFetchEvent, type AttachmentFetchEventCompleted, type AttachmentFetchEventDeleted, type AttachmentFetchEventProgress, type AttachmentFetchEventType, AttachmentFetcher, type AttachmentMetadata, AttachmentToken, type AuthenticationHandler, type AuthenticationStatus, Authenticator, BasePendingCursorOperation, BasePendingIDSpecificOperation, CBOR, Collection, type CollectionInterface, CollectionsEvent, type CollectionsEventParams, type CollectionsObservationHandler, type ConditionSource, type Connection, type ConnectionType, Counter, type CustomLogCallback, type DQLQueryArgumentValue, type DQLQueryArguments, Ditto, DittoError, Document, DocumentID, type DocumentIDValue, DocumentPath, type DocumentValue, ERROR_CODES, type ErrorCode, type ErrorContext, type Identity, type IdentityManual, type IdentityOfflinePlayground, type IdentityOnlinePlayground, type IdentityOnlineWithAuthentication, type IdentitySharedKey, IdentityTypesRequiringOfflineLicenseToken, type InitOptions, KeepAlive, LiveQuery, type LiveQueryEvent, LiveQueryEventInitial, LiveQueryEventUpdate, type LiveQueryEventUpdateParams, type LiveQueryMove, type LogLevel, Logger, MutableCounter, MutableDocument, MutableDocumentPath, MutableRegister, NotAvailableAuthenticator, Observer, type ObserverOptions, OnlineAuthenticator, type Peer, PendingCollectionsOperation, PendingCursorOperation, PendingIDSpecificOperation, Presence, type PresenceConnectionType, type PresenceGraph, type QueryArguments, type QueryObservationHandler, QueryResult, QueryResultItem, Register, type RemotePeer, SingleDocumentLiveQueryEvent, type SingleObservationHandler, SmallPeerInfo, type SmallPeerInfoSyncScope, type SortDirection, Store, type StoreObservationHandler, type StoreObservationHandlerWithSignalNext, StoreObserver, Subscription, Sync, type SyncParameters, type SyncState, SyncSubscription, type TransportCondition, TransportConfig, type TransportConfigConnect, type TransportConfigGlobal, type TransportConfigLan, type TransportConfigListen, type TransportConfigListenHTTP, type TransportConfigListenTCP, type TransportConfigPeerToPeer, type TypedAttachmentToken, type UntypedAttachmentToken, UpdateResult, type UpdateResultType, UpdateResultsMap, type UpsertOptions, type WebAssemblyModule, type WriteStrategy, WriteTransaction, WriteTransactionCollection, WriteTransactionPendingCursorOperation, WriteTransactionPendingIDSpecificOperation, type WriteTransactionResult, addressToString, checkAPIs, disableDeadlockTimeoutWhenDebugging, getBridgeLoad, init, mapFFIErrors, mapFFIErrorsAsync, transportConfigFromDeserializable, transportConfigToSerializable, validateAttachmentMetadata, validateDocumentIDCBOR, validateDocumentIDValue };
+export { type Address, Attachment, type AttachmentFetchEvent, type AttachmentFetchEventCompleted, type AttachmentFetchEventDeleted, type AttachmentFetchEventProgress, type AttachmentFetchEventType, AttachmentFetcher, type AttachmentMetadata, AttachmentToken, type AuthenticationHandler, type AuthenticationStatus, Authenticator, BasePendingCursorOperation, BasePendingIDSpecificOperation, CBOR, Collection, type CollectionInterface, CollectionsEvent, type CollectionsEventParams, type CollectionsObservationHandler, type ConditionSource, type Connection, ConnectionRequest, type ConnectionRequestAuthorization, type ConnectionRequestHandler, type ConnectionType, Counter, type CustomLogCallback, type DQLQueryArgumentValue, type DQLQueryArguments, Ditto, DittoError, Document, DocumentID, type DocumentIDValue, DocumentPath, type DocumentValue, ERROR_CODES, type ErrorCode, type ErrorContext, type Identity, type IdentityManual, type IdentityOfflinePlayground, type IdentityOnlinePlayground, type IdentityOnlineWithAuthentication, type IdentitySharedKey, IdentityTypesRequiringOfflineLicenseToken, type InitOptions, KeepAlive, LiveQuery, type LiveQueryEvent, LiveQueryEventInitial, LiveQueryEventUpdate, type LiveQueryEventUpdateParams, type LiveQueryMove, type LogLevel, Logger, MutableCounter, MutableDocument, MutableDocumentPath, MutableRegister, NotAvailableAuthenticator, Observer, type ObserverOptions, OnlineAuthenticator, type Peer, PendingCollectionsOperation, PendingCursorOperation, PendingIDSpecificOperation, Presence, type PresenceConnectionType, type PresenceGraph, type QueryArguments, type QueryObservationHandler, QueryResult, QueryResultItem, Register, type RemotePeer, SingleDocumentLiveQueryEvent, type SingleObservationHandler, SmallPeerInfo, type SmallPeerInfoSyncScope, type SortDirection, Store, type StoreObservationHandler, type StoreObservationHandlerWithSignalNext, StoreObserver, Subscription, Sync, type SyncParameters, type SyncState, SyncSubscription, type TransportCondition, TransportConfig, type TransportConfigConnect, type TransportConfigGlobal, type TransportConfigLan, type TransportConfigListen, type TransportConfigListenHTTP, type TransportConfigListenTCP, type TransportConfigPeerToPeer, type TypedAttachmentToken, type UntypedAttachmentToken, UpdateResult, type UpdateResultType, UpdateResultsMap, type UpsertOptions, type WebAssemblyModule, type WriteStrategy, WriteTransaction, WriteTransactionCollection, WriteTransactionPendingCursorOperation, WriteTransactionPendingIDSpecificOperation, type WriteTransactionResult, addressToString, checkAPIs, disableDeadlockTimeoutWhenDebugging, getBridgeLoad, init, mapFFIErrors, mapFFIErrorsAsync, transportConfigFromDeserializable, transportConfigToSerializable, validateAttachmentMetadata, validateDocumentIDCBOR, validateDocumentIDValue };
 //# sourceMappingURL=ditto.d.ts.map