@marteye/studiojs 1.0.0 → 1.1.1

package/README.md

@@ -0,0 +1,53 @@
+# MartEye Studio JavaScript SDK (@marteye/studiojs)
+
+This library is a JavaScript SDK that allows you to easily integrate with MartEye Studio's API. It provides methods to interact with various resources, manage data, and leverage the powerful features offered by MartEye Studio.
+
+## Installation
+
+You can install the library using npm or yarn:
+
+Using npm:
+
+```bash
+npm install @marteye/studiojs
+```
+
+Using yarn:
+
+```bash
+yarn add @marteye/studiojs
+```
+
+## Usage
+
+### Importing the Library
+
+Using ES Modules:
+
+```javascript
+import StudioJS from "@marteye/studiojs";
+```
+
+Or using CommonJS:
+
+```javascript
+let StudioJS = require("@marteye/studiojs");
+```
+
+### Initializing the SDK
+
+Before using the library, initialize it with your API key. For more information on obtaining an API key, please contact your MartEye representative.
+
+```javascript
+let studioClient = StudioJS.init({
+  apiKey: "YOUR_API_KEY_HERE",
+});
+```
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request if you have suggestions or improvements.
+
+## License
+
+MIT

package/dist/createApp.d.ts

@@ -0,0 +1,64 @@
+import { WebhookEventName } from "./types";
+/**
+ * Headers used by Studio to identify webhook and action requests
+ */
+export declare const StudioHeaders: {
+    marketId: string;
+    webhookId: string;
+    action: string;
+    apiKey: string;
+    signature: string;
+};
+export interface StudioManifest {
+    id: string;
+    name: string;
+    version: string;
+    description: string;
+    icon: string;
+    author: string;
+    actions: {
+        name: string;
+        url: string;
+    }[];
+    webhooks: {
+        url: string;
+        triggers: WebhookEventName[];
+    }[];
+    parameterConfig: {
+        id: string;
+        type: "string" | "number" | "boolean" | "string[]" | "password";
+        label: string;
+        description?: string;
+        required?: boolean;
+        defaultValue?: string | number | boolean | string[];
+    }[];
+}
+/***
+ * Creates an app manifest used to describe the app to Studio
+ *
+ * @param appConfig
+ * @returns
+ */
+export declare function createAppManifest(appConfig: {
+    id: string;
+    name: string;
+    version: string;
+    description: string;
+    icon: string;
+    author: string;
+}): {
+    addWebhook: (url: string, triggers: WebhookEventName[]) => void;
+    addConfig: (config: {
+        id: string;
+        type: "string" | "number" | "boolean" | "string[]" | "password";
+        label: string;
+        description?: string;
+        required?: boolean;
+        defaultValue?: string | number | boolean | string[];
+    }) => void;
+    addAction: (action: {
+        name: string;
+        url: string;
+    }) => void;
+    readonly manifest: StudioManifest;
+};

package/dist/index.d.ts

@@ -0,0 +1,477 @@
+type Timestamp = string;
+type SuperType = "Sheep" | "Goats" | "Cattle" | "Pigs" | "Horses" | "Deer" | "Poultry" | "Machinery" | "Antiques" | "Other";
+type Currency = "GBP" | "EUR" | "USD";
+type SupportedCountryCode = "GB-ENG" | "GB-SCT" | "GB-WLS" | "GB-NIR" | "IE";
+type CurrenciesWithGuinea = Currency | "GUINEA-GBP";
+type UnitOfSale = "Per KG" | "Per Item" | "Per Lot" | "Per 1000KG";
+interface Market {
+    id: string;
+    createdAt: Timestamp;
+    updatedAt: Timestamp;
+    name: string;
+    description: string;
+    logo: string;
+    primaryColour: string;
+    secondaryColour: string;
+    countryCode: SupportedCountryCode;
+    address: Address;
+    telephone?: string;
+    vatNumber?: string;
+    email?: string;
+    movementLocationNumbers?: {
+        number: string;
+        type: "CPH" | "Herd Number" | "Flock Number" | "Other";
+        createdAt: Timestamp;
+    }[];
+    paymentInstructions?: string;
+}
+type AttributeValueType = string | number | boolean | Timestamp | Media;
+interface Sale {
+    id: string;
+    createdAt: Timestamp;
+    updatedAt: Timestamp;
+    updatedBy?: string | null;
+    startsAt: Timestamp;
+    closedAt?: Timestamp | null;
+    marketId: string;
+    name: string;
+    recurring?: null | "Weekly" | "Bi-weekly" | "Monthly";
+    defaultProductCode: string;
+    /**
+     * Default attributes values for any new lot item
+     */
+    attributeDefaults?: {
+        [attributekey: string]: AttributeValueType;
+    };
+    /**
+     * the codes that are allowed for the sale
+     */
+    availableProductCodes: string[];
+    /**
+     * the supertypes from the product codes. e..g Cattle, Sheep, Pigs etc
+     */
+    superTypes: SuperType[];
+    attributeSet: AttributeDefinition[];
+    attributeSetByProductCode: {
+        [code: string]: string[];
+    };
+    currentLotGroup?: string | null;
+    nextLotGroup?: string | null;
+    /**
+     * Auto queue the next lot when the current lot is sold in rostrum
+     */
+    autoQueue?: boolean;
+    /**
+     * The sale profile ID to use for this sale. Which is used to find settings specific devices and printers etc.
+     */
+    saleProfileId?: string | null;
+    /**
+     * Show the display board
+     */
+    displayBoard?: boolean;
+    martEyeId?: string | null;
+    marteyeSettings?: MartEyeTimedSaleSettings | MartEyeLiveSaleSettings | null;
+}
+interface MartEyeLiveSaleSettings {
+    description?: string;
+    image?: string;
+    logo?: string;
+    type: "LIVE";
+    location?: string | null;
+    descriptionLines?: string[];
+    descriptionLink?: string;
+    deposit?: number;
+    hidePrices?: boolean;
+    hideReplay?: boolean;
+    labels?: string[];
+    tags?: string[];
+}
+interface MartEyeTimedSaleSettings {
+    description?: string;
+    image?: string;
+    logo?: string;
+    type: "TIMED";
+    /**
+     * The location of the sale. This could be a physical location Ring 1 / Ring 2 / Farm Address etc
+     */
+    location?: string | null;
+    details?: {
+        markdownBase64: string;
+        title: string;
+    }[];
+    cover?: string;
+    primaryColour?: string;
+    secondaryColour?: string;
+    foregroundColour?: string;
+    extensionTime: number;
+    incrementLadder: IncrementLadder;
+    hideNav?: boolean;
+    signInOverrideLink?: string;
+    published?: boolean;
+    pin?: boolean;
+    labels?: string[];
+    deposit?: number;
+    cascade?: boolean;
+    reportEmail?: string;
+}
+type IncrementLadder = IncrementLadderItem[];
+interface IncrementLadderItem {
+    max: number;
+    increment: number;
+}
+type LotSaleStatus = "Sold" | "Unsold" | "Rerun" | "Resold" | null;
+interface Lot {
+    id: string;
+    saleId: string;
+    marketId: string;
+    createdAt: Timestamp;
+    updatedAt: Timestamp;
+    updatedBy?: string | null;
+    productCode: string;
+    superType?: SuperType;
+    isLivestock?: boolean;
+    attributes: {
+        [key: string]: AttributeValueType;
+    };
+    loadingAttributes?: {
+        [attributePath: string]: {
+            id: string;
+            startAt: Timestamp;
+            path: string;
+        };
+    };
+    itemMap: {
+        [itemId: string]: LotItem;
+    };
+    sellerCasual?: string | null;
+    sellerCustomerId: string | null;
+    seller?: ShortCustomerDetails;
+    lotNumber?: string | null;
+    index: number;
+    group?: string;
+    remarks?: string;
+    notes?: string;
+    currency: CurrenciesWithGuinea;
+    unitOfSale: UnitOfSale;
+    unitPriceInCents?: number;
+    buyerCasual?: string | null;
+    buyerCustomerId: string | null;
+    buyer?: ShortCustomerDetails | null;
+    startedAt?: Timestamp;
+    endedAt?: Timestamp;
+    sellerInvoiceId: string | null;
+    sellerInvoiceNumber?: number | undefined | null;
+    buyerInvoiceId: string | null;
+    buyerInvoiceNumber?: number | undefined | null;
+    voidedSellerInvoiceIds?: string[];
+    voidedBuyerInvoiceIds?: string[];
+    saleStatus?: LotSaleStatus;
+    void?: boolean;
+    originalLot?: string;
+    metadata: {
+        [key: string]: any;
+    };
+    generated?: LotGeneratedValues;
+    issues?: {
+        [issueId: string]: LotIssue;
+    };
+    resolvedIssues?: {
+        [issueId: string]: LotIssue;
+    };
+    /***
+     * Default values for any new lot item
+     */
+    itemAttributeDefaults?: {
+        [attributekey: string]: AttributeValueType;
+    };
+}
+type LotIssueCode = "unknown-attribute" | "validation-error" | "staff-flagged";
+interface LotIssue {
+    id: string;
+    itemId?: string | null;
+    path?: string | null;
+    code: LotIssueCode;
+    description: string;
+    severity: "error" | "warning" | "info";
+    createdAt: Timestamp;
+    createdBy: string;
+    blockCheckout: boolean;
+}
+interface LotGeneratedValues {
+    totalValueInCents?: number | null;
+    description?: string | null;
+    pricePerKiloInCents?: number | null;
+    averageWeightKg?: number | null;
+    pricePerItemInCents?: number | null;
+    countOfItems?: number | null;
+}
+interface ShortCustomerDetails {
+    isSet: boolean;
+    id?: string;
+    copiedInAt?: Timestamp;
+    accountNumber?: string;
+    bidderNumber?: number | null;
+    displayName?: string;
+    avatar?: string | null;
+}
+interface LotItem {
+    id: string;
+    createdAt: Timestamp;
+    updatedAt: Timestamp;
+    updatedBy?: string | null;
+    index: number;
+    attributes: {
+        [key: string]: AttributeValueType;
+    };
+    notes: {
+        id: string;
+        text: string;
+        createdAt: Timestamp;
+    }[];
+    metadata: {
+        [key: string]: string | number | boolean | Timestamp | Media;
+    };
+}
+interface Address {
+    id: string;
+    nickname?: string;
+    company?: string;
+    firstName?: string;
+    lastName?: string;
+    address1: string;
+    address2?: string;
+    city: string;
+    province?: string;
+    zip: string;
+    country: string;
+}
+interface ImageThumbnail {
+    url: string;
+    width: number;
+    height: number;
+}
+interface Media {
+    id: string;
+    url: string;
+    type: "image/jpeg" | "image/png" | "video/mp4" | "application/pdf";
+    filename: string;
+    thumbnails?: {
+        small?: ImageThumbnail;
+        medium?: ImageThumbnail;
+        large?: ImageThumbnail;
+    };
+}
+type WebhookEventName = "market.updated" | "sale.created" | "sale.updated" | "sale.deleted" | "lot.created" | "lot.updated" | "lot.deleted" | "lot.media.created" | "lot.media.deleted" | "invoice.created" | "invoice.updated" | "invoice.deleted" | "payment.created" | "payment.updated" | "payment.deleted" | "payout.created" | "payout.updated" | "payout.deleted" | "customer.created" | "customer.updated" | "customer.deleted" | "member.created" | "member.updated" | "member.deleted";
+type SupportedAttributeTypes = "string" | "number" | "boolean" | "date" | "datetime" | "time";
+interface AttributeDefinition {
+    id: string;
+    name: string;
+    shortName?: string;
+    description?: string;
+    applyTo: string[];
+    level: "item" | "lot";
+    readonly?: boolean;
+    lotDetailFlyoutGroup?: string;
+    buyerCheckoutGroup?: string;
+    sellerCheckoutGroup?: string;
+    buyerCustomerAttribute?: boolean;
+    sellerCustomerAttribute?: boolean;
+    defaultHiddenOnSaleSheet?: boolean;
+    prefillableFromPreviousLot?: boolean;
+    hidden?: boolean;
+    showInSellerDetailsPanel?: boolean;
+    displayTemplate?: string;
+    displayTemplateMultiValue?: string;
+    type: SupportedAttributeTypes;
+    requiredPreSale: boolean;
+    requiredToCheckout: boolean;
+    minValue?: number;
+    maxValue?: number;
+    minLength?: number;
+    maxLength?: number;
+    regexPattern?: string;
+    minDateExpression?: string;
+    maxDateExpression?: string;
+    allowedValues?: string[];
+}
+
+declare function Studio(apiKey: string, baseUrl?: string, defaultTimeout?: number, debug?: boolean): {
+    isDebugMode: boolean;
+    markets: {
+        get: (marketId: string) => Promise<Market>;
+    };
+    sales: {
+        get: (marketId: string, saleId: string) => Promise<Sale>;
+        list: (marketId: string, opts: {
+            start?: string | undefined;
+            end?: string | undefined;
+        }) => Promise<{
+            start: string;
+            end: string;
+            sales: Sale[];
+        }>;
+        update: (marketId: string, saleId: string, data: {
+            name?: string | undefined;
+            recurring?: "Weekly" | "Bi-weekly" | "Monthly" | null | undefined;
+            defaultProductCode?: string | undefined;
+            attributeDefaults?: Record<string, any> | undefined;
+            martEyeId?: string | null | undefined;
+            marteyeSettings?: {
+                description?: string | undefined;
+                image?: string | undefined;
+                logo?: string | undefined;
+                type: "LIVE" | "TIMED";
+                location?: string | null | undefined;
+                descriptionLines?: string[] | undefined;
+                descriptionLink?: string | undefined;
+                deposit?: number | undefined;
+                hidePrices?: boolean | undefined;
+                hideReplay?: boolean | undefined;
+                labels?: string[] | undefined;
+                tags?: string[] | undefined;
+                details?: {
+                    markdownBase64: string;
+                    title: string;
+                }[] | undefined;
+                cover?: string | undefined;
+                primaryColour?: string | undefined;
+                secondaryColour?: string | undefined;
+                foregroundColour?: string | undefined;
+                extensionTime?: number | undefined;
+                incrementLadder?: {
+                    max: number;
+                    increment: number;
+                }[] | undefined;
+                hideNav?: boolean | undefined;
+                signInOverrideLink?: string | undefined;
+                published?: boolean | undefined;
+                pin?: boolean | undefined;
+                cascade?: boolean | undefined;
+                reportEmail?: string | undefined;
+            } | null | undefined;
+        }) => Promise<Sale>;
+    };
+    lots: {
+        get: (marketId: string, saleId: string, lotId: string) => Promise<Lot>;
+        list: (marketId: string, saleId: string) => Promise<Lot[]>;
+        create: (marketId: string, saleId: string, data: {
+            index?: number | undefined;
+            lotNumber?: string | undefined;
+            group?: string | undefined;
+            productCode?: string | undefined;
+            sellerCustomerId?: string | undefined;
+            attributes?: Record<string, any> | undefined;
+            metadata?: Record<string, any> | undefined;
+            buyerCustomerId?: string | undefined;
+            unitPriceInCents?: number | undefined;
+            startedAt?: string | undefined;
+            endedAt?: string | undefined;
+            previousLotNumber?: string | undefined;
+        }) => Promise<Lot>;
+        update: (marketId: string, saleId: string, lotId: string, data: {
+            productCode?: string | undefined;
+            attributes?: Record<string, any> | undefined;
+            sellerCasual?: string | null | undefined;
+            sellerCustomerId?: string | null | undefined;
+            lotNumber?: string | null | undefined;
+            remarks?: string | undefined;
+            notes?: string | undefined;
+            unitOfSale?: "Per KG" | "Per Item" | "Per Lot" | "Per 1000KG" | undefined;
+            unitPriceInCents?: number | undefined;
+            buyerCasual?: string | null | undefined;
+            buyerCustomerId?: string | null | undefined;
+            startedAt?: string | null | undefined;
+            endedAt?: string | null | undefined;
+            saleStatus?: "Sold" | "Unsold" | "Rerun" | "Resold" | null | undefined;
+            metadata?: Record<string, any> | undefined;
+        }) => Promise<Lot>;
+        delete: (marketId: string, saleId: string, lotId: string) => Promise<unknown>;
+    };
+    lotitems: {
+        create: (marketId: string, saleId: string, lotId: string, data: {
+            attributes?: Record<string, any> | undefined;
+            notes?: {
+                text: string;
+            }[] | undefined;
+            metadata?: Record<string, any> | undefined;
+        }) => Promise<LotItem>;
+        update: (marketId: string, saleId: string, lotId: string, itemId: string, data: {
+            attributes?: Record<string, any> | undefined;
+            index?: number | undefined;
+            metadata?: Record<string, any> | undefined;
+        }) => Promise<LotItem>;
+        delete: (marketId: string, saleId: string, lotId: string, itemId: string) => Promise<unknown>;
+    };
+    webhooks: {
+        constructEvent: (bodyAsBuffer: Buffer, signature: string, endpointSecret: string) => Promise<any>;
+    };
+    actions: {
+        constructAction: (bodyAsBuffer: Buffer, signature: string, endpointSecret: string) => Promise<any>;
+    };
+};
+
+/**
+ * Headers used by Studio to identify webhook and action requests
+ */
+declare const StudioHeaders: {
+    marketId: string;
+    webhookId: string;
+    action: string;
+    apiKey: string;
+    signature: string;
+};
+interface StudioManifest {
+    id: string;
+    name: string;
+    version: string;
+    description: string;
+    icon: string;
+    author: string;
+    actions: {
+        name: string;
+        url: string;
+    }[];
+    webhooks: {
+        url: string;
+        triggers: WebhookEventName[];
+    }[];
+    parameterConfig: {
+        id: string;
+        type: "string" | "number" | "boolean" | "string[]" | "password";
+        label: string;
+        description?: string;
+        required?: boolean;
+        defaultValue?: string | number | boolean | string[];
+    }[];
+}
+/***
+ * Creates an app manifest used to describe the app to Studio
+ *
+ * @param appConfig
+ * @returns
+ */
+declare function createAppManifest(appConfig: {
+    id: string;
+    name: string;
+    version: string;
+    description: string;
+    icon: string;
+    author: string;
+}): {
+    addWebhook: (url: string, triggers: WebhookEventName[]) => void;
+    addConfig: (config: {
+        id: string;
+        type: "string" | "number" | "boolean" | "string[]" | "password";
+        label: string;
+        description?: string;
+        required?: boolean;
+        defaultValue?: string | number | boolean | string[];
+    }) => void;
+    addAction: (action: {
+        name: string;
+        url: string;
+    }) => void;
+    readonly manifest: StudioManifest;
+};
+
+export { Studio, StudioHeaders, type StudioManifest, createAppManifest, Studio as default };