@flashbacktech/flashbackclient 0.0.13

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Flashback, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+# @flashbacktech/flashonstellar
+
+TypeScript/JavaScript client for:
+
+- interacting with the FlashOnStellar storage system on the Stellar blockchain.
+- offering your available storage capacity as a provider on the FlashOnStellar system.
+- connecting your applications as a consumer of storage on the FlashOnStellar system.
+
+## Installation
+
+```bash
+npm install @flashbacktech/flashonstellar
+```
+
+## Usage
+
+### Client Library
+
+```typescript
+import { FlashOnStellarClient, StellarNetwork } from '@flashbacktech/flashonstellar/client';
+```
+
+See the [Stellar README](STELLAR.md) for usage instructions.
+
+### Consumer API reference
+
+See the [Consumer README](./src/consumer/README.md) for usage instructions.
+
+### Provider API reference
+
+See the [Provider README](./src/provider/README.md) for usage instructions.
+
+## License
+
+ISC © [2025] FlashBack Inc.

package/dist/stellar/client.d.ts

@@ -0,0 +1,282 @@
+import { StellarNetwork } from './transaction.js';
+/**
+ * Configuration interface for the FlashOnStellar client
+ * @interface FlashOnStellarClientConfig
+ */
+interface FlashOnStellarClientConfig {
+    /** Stellar contract address for the FlashOnStellar system */
+    contractAddress: string;
+    /**
+     * Optional callback function to sign non-read Stellar transactions
+     * @param xdrToSign - The XDR-encoded transaction to sign
+     * @returns Promise resolving to the signed XDR string
+     */
+    signTransaction?: (xdrToSign: string) => Promise<string>;
+    /** Network configuration for Stellar (testnet/public) */
+    network: StellarNetwork;
+}
+type ClientContext = FlashOnStellarClientConfig;
+/**
+ * Main client class for interacting with the FlashOnStellar system
+ * This client provides methods for managing providers, consumers, units, and reservations
+ * on the Stellar blockchain.
+ */
+declare class FlashOnStellarClient {
+    private readonly signTransaction?;
+    private readonly contractAddress;
+    private readonly network;
+    protected getContext(): ClientContext;
+    /**
+     * Creates a new instance of the FlashOnStellarClient
+     * @param config - Configuration options for the client
+     */
+    constructor(config: FlashOnStellarClientConfig);
+    /**
+     * Derives a public key from a private key
+     * @param privateKey - Stellar private key
+     * @returns The corresponding public key
+     */
+    getPublicKey: (privateKey: string) => string;
+    /**
+     * Signs a transaction using the provided private key using Stellar SDK
+     * The alternative is providing your own signing function (for example, using Wallet Kit).
+     * @param xdrToSign - XDR-encoded transaction to sign
+     * @param privateKey - Stellar private key to sign with
+     * @returns Promise resolving to the signed XDR string
+     */
+    signTransactionWithKey: (xdrToSign: string, privateKey: string) => Promise<string>;
+    /**
+     * Retrieves stats for the current user
+     * @param wallet_address - Address of the wallet requesting the information
+     * @returns Promise resolving to DashboardStats object
+     */
+    get_stats: (wallet_address: string) => Promise<import("./models.js").ContractStats | null>;
+    /**
+     * Retrieves provider information
+     * @param wallet_address - Address of the wallet requesting the information
+     * @param provider_address - Address of the provider to retrieve
+     * @param load_units - Optional flag to include provider's units in the response
+     * @returns Promise resolving to StorageProvider object
+     */
+    get_provider: (wallet_address: string, provider_address: string, load_units?: boolean) => Promise<import("./models.js").StorageProvider | null>;
+    /**
+     * Retrieves all units associated with a provider
+     * @param wallet_address - Address of the wallet requesting the information
+     * @param provider_address - Address of the provider
+     * @returns Promise resolving to an array of StorageUnit objects
+     */
+    get_provider_units: (wallet_address: string, provider_address: string) => Promise<Map<number, import("./models.js").StorageUnit>>;
+    /**
+     * Retrieves a paginated list of providers
+     * @param wallet_address - Address of the wallet requesting the information
+     * @param skip - Number of items to skip for pagination
+     * @param take - Number of items to take per page
+     * @returns Promise resolving to an array of StorageProvider objects
+     */
+    get_providers: (wallet_address: string, skip?: number, take?: number) => Promise<Map<string, import("./models.js").StorageProvider>>;
+    /**
+     * Gets the total count of providers in the system
+     * @param wallet_address - Address of the wallet requesting the information
+     * @returns Promise resolving to the total number of providers
+     */
+    get_provider_count: (wallet_address: string) => Promise<number>;
+    /**
+     * Registers a new provider in the system
+     * @param wallet_address - Address of the wallet registering the provider
+     * @param provider_address - Address for the new provider
+     * @param provider_description - Description of the provider
+     * @returns Promise resolving to the registration transaction result
+     * @requires Signature - This method requires a transaction signature
+     * @throws Will throw if provider address is already registered
+     */
+    register_provider(wallet_address: string, provider_address: string, provider_description: string): Promise<void>;
+    /**
+     * Deletes a provider from the system
+     * @param wallet_address - Address of the wallet making the request
+     * @param provider_address - Address of the provider to delete
+     * @returns Promise resolving to the deletion transaction result
+     * @requires Signature - This method requires a transaction signature
+     */
+    delete_provider(wallet_address: string, provider_address: string): Promise<void>;
+    /**
+     * Updates provider information
+     * @param wallet_address - Address of the wallet making the request
+     * @param provider_address - Address of the provider to update
+     * @param provider_description - New description for the provider
+     * @returns Promise resolving to the update transaction result
+     * @requires Signature - This method requires a transaction signature
+     */
+    update_provider(wallet_address: string, provider_address: string, provider_description: string): Promise<void>;
+    /**
+     * Retrieves consumer information
+     * @param wallet_address - Address of the wallet requesting the information
+     * @param consumer_address - Address of the consumer to retrieve
+     * @param load_reservations - Optional flag to include consumer's reservations
+     * @returns Promise resolving to StorageConsumer object
+     */
+    get_consumer: (wallet_address: string, consumer_address: string, load_reservations?: boolean) => Promise<import("./models.js").StorageConsumer | null>;
+    /**
+     * Retrieves a paginated list of consumers
+     * @param wallet_address - Address of the wallet requesting the information
+     * @param skip - Number of items to skip for pagination
+     * @param take - Number of items to take per page
+     * @returns Promise resolving to an array of StorageConsumer objects
+     */
+    get_consumers: (wallet_address: string, skip?: number, take?: number) => Promise<Map<string, import("./models.js").StorageConsumer>>;
+    /**
+     * Gets the total count of consumers in the system
+     * @param wallet_address - Address of the wallet requesting the information
+     * @returns Promise resolving to the total number of consumers
+     */
+    get_consumer_count: (wallet_address: string) => Promise<number>;
+    /**
+     * Retrieves all reservations associated with a consumer
+     * @param wallet_address - Address of the wallet requesting the information
+     * @param consumer_address - Address of the consumer
+     * @returns Promise resolving to an array of StorageReservation objects
+     */
+    get_consumer_reservations: (wallet_address: string, consumer_address: string) => Promise<Map<number, import("./models.js").StorageReservation>>;
+    /**
+     * Registers a new consumer in the system
+     * @param wallet_address - Address of the wallet registering the consumer
+     * @param consumer_address - Address for the new consumer
+     * @param consumer_description - Description of the consumer
+     * @returns Promise resolving to the registration transaction result
+     * @requires Signature - This method requires a transaction signature
+     */
+    register_consumer(wallet_address: string, consumer_address: string, consumer_description: string): Promise<void>;
+    delete_consumer(wallet_address: string, consumer_address: string): Promise<void>;
+    update_consumer(wallet_address: string, consumer_address: string, consumer_description: string): Promise<void>;
+    /**
+     * Registers a new storage unit in the system
+     * @param wallet_address - Address of the wallet registering the unit
+     * @param provider_address - Address of the provider owning the unit
+     * @param capacity - Capacity of the storage unit in gigabytes
+     * @param endpoint - Endpoint for the storage unit
+     * @returns Promise resolving to the registration transaction result
+     * @requires Signature - This method requires a transaction signature
+     */
+    register_unit(wallet_address: string, provider_address: string, capacity: number, endpoint: string): Promise<[unitId: number, unit: import("./models.js").StorageUnit] | null>;
+    /**
+     * Retrieves storage unit information
+     * @param wallet_address - Address of the wallet requesting the information
+     * @param unit_id - Identifier of the storage unit
+     * @param load_reservations - Optional flag to include unit's reservations
+     * @returns Promise resolving to StorageUnit object
+     */
+    get_unit: (wallet_address: string, unit_id: number, load_reservations?: boolean) => Promise<import("./models.js").StorageUnit | null>;
+    /**
+     * Retrieves all reservations for a specific storage unit
+     * @param wallet_address - Address of the wallet requesting the information
+     * @param unit_id - Identifier of the storage unit
+     * @returns Promise resolving to an array of StorageReservation objects
+     */
+    get_unit_reservations: (wallet_address: string, unit_id: number) => Promise<Map<number, import("./models.js").StorageReservation>>;
+    /**
+     * Deletes a storage unit from the system
+     * @param wallet_address - Address of the wallet making the request
+     * @param provider_address - Address of the provider owning the unit
+     * @param unit_id - Identifier of the storage unit
+     * @returns Promise resolving to the deletion transaction result
+     * @requires Signature - This method requires a transaction signature
+     * @throws Will throw if unit has active reservations
+     */
+    delete_unit(wallet_address: string, provider_address: string, unit_id: number): Promise<import("./models.js").DeletionStatus | null>;
+    /**
+     * Places a storage unit into maintenance mode
+     * @param wallet_address - Address of the wallet making the request
+     * @param provider_address - Address of the provider owning the unit
+     * @param unit_id - Identifier of the storage unit
+     * @param maintenance_start - Start date of maintenance period
+     * @param maintenance_end - End date of maintenance period
+     * @returns Promise resolving to the maintenance transaction result
+     * @requires Signature - This method requires a transaction signature
+     * @throws Will throw if unit has active reservations that conflict with the maintenance window
+     */
+    enter_maintenance(wallet_address: string, provider_address: string, unit_id: number, maintenance_start: Date, maintenance_end: Date): Promise<boolean | null>;
+    /**
+     * Exits maintenance mode for a storage unit
+     * @param wallet_address - Address of the wallet making the request
+     * @param provider_address - Address of the provider owning the unit
+     * @param unit_id - Identifier of the storage unit
+     * @returns Promise resolving to the maintenance exit transaction result
+     * @requires Signature - This method requires a transaction signature
+     * @throws Will throw if unit is not in maintenance mode
+     */
+    exit_maintenance(wallet_address: string, provider_address: string, unit_id: number): Promise<boolean | null>;
+    /**
+     * Places a storage unit into decommissioning mode
+     * This starts the process of removing the unit from service.
+     * @param wallet_address - Address of the wallet making the request
+     * @param provider_address - Address of the provider owning the unit
+     * @param unit_id - Identifier of the storage unit
+     * @returns Promise resolving to the decommissioning transaction result
+     * @requires Signature - This method requires a transaction signature
+     * @throws Will throw if unit has active reservations
+     */
+    enter_decommissioning(wallet_address: string, provider_address: string, unit_id: number): Promise<boolean | null>;
+    /**
+     * Exits decommissioning mode for a storage unit
+     * This cancels the decommissioning process and returns the unit to service.
+     * @param wallet_address - Address of the wallet making the request
+     * @param provider_address - Address of the provider owning the unit
+     * @param unit_id - Identifier of the storage unit
+     * @returns Promise resolving to the decommissioning exit transaction result
+     * @requires Signature - This method requires a transaction signature
+     * @throws Will throw if unit is not in decommissioning mode
+     */
+    exit_decommissioning(wallet_address: string, provider_address: string, unit_id: number): Promise<boolean | null>;
+    /**
+     * Retrieves information about a specific reservation
+     * @param wallet_address - Address of the wallet requesting the information
+     * @param reservation_id - Identifier of the reservation
+     * @returns Promise resolving to StorageReservation object
+     */
+    get_reservation: (wallet_address: string, reservation_id: number) => Promise<import("./models.js").StorageReservation | null>;
+    /**
+     * Creates a new storage reservation
+     * @param wallet_address - Address of the wallet making the request
+     * @param consumer_address - Address of the consumer requesting storage
+     * @param unit_id - Identifier of the storage unit to reserve
+     * @param reserved_gb - Amount of storage to reserve in gigabytes
+     * @returns Promise resolving to the reservation creation transaction result
+     * @requires Signature - This method requires a transaction signature
+     * @throws Will throw if unit doesn't have enough available capacity
+     * @throws Will throw if unit is in maintenance or decommissioning mode
+     */
+    reserve_unit(wallet_address: string, consumer_address: string, unit_id: number, reserved_gb: number): Promise<boolean>;
+    /**
+     * Deletes an existing reservation
+     * @param wallet_address - Address of the wallet making the request
+     * @param consumer_address - Address of the consumer who owns the reservation
+     * @param reservation_id - Identifier of the reservation to delete
+     * @returns Promise resolving to the reservation deletion transaction result
+     * @requires Signature - This method requires a transaction signature
+     * @throws Will throw if reservation has non-zero inuse_bytes
+     */
+    delete_reservation(wallet_address: string, consumer_address: string, reservation_id: number): Promise<import("./models.js").DeletionStatus>;
+    /**
+     * Updates the amount of storage currently in use by a consumer
+     * @param wallet_address - Address of the wallet making the request
+     * @param consumer_address - Address of the consumer
+     * @param reservation_id - Identifier of the reservation
+     * @param inuse_bytes - Current number of bytes in use
+     * @returns Promise resolving to the update transaction result
+     * @requires Signature - This method requires a transaction signature
+     * @throws Will throw if inuse_bytes exceeds reserved amount
+     */
+    update_inuse_bytes_consumer(wallet_address: string, consumer_address: string, reservation_id: number, inuse_bytes: number): Promise<boolean>;
+    /**
+     * Updates the amount of storage currently in use, reported by provider
+     * @param wallet_address - Address of the wallet making the request
+     * @param provider_address - Address of the provider
+     * @param reservation_id - Identifier of the reservation
+     * @param inuse_bytes - Current number of bytes in use
+     * @returns Promise resolving to the update transaction result
+     * @requires Signature - This method requires a transaction signature
+     * @throws Will throw if inuse_bytes exceeds reserved amount
+     * @throws Will throw if provider's report differs significantly from consumer's report
+     */
+    update_inuse_bytes_provider(wallet_address: string, provider_address: string, reservation_id: number, inuse_bytes: number): Promise<boolean>;
+}
+export { FlashOnStellarClient, FlashOnStellarClientConfig, ClientContext };