investec-card-api/dist/index.d.cts

A simple package for interacting with Investec's programmable banking card API

/**
 * Represents the response from the authentication endpoint.
 */
interface AuthResponse {
    access_token: string;
    token_type: string;
    expires_in: number;
    scope: string;
}
/**
 * Represents a generic reference response containing a list of code-name pairs.
 */
interface ReferenceResponse {
    data: {
        result: Array<{
            Code: string;
            Name: string;
        }>;
    };
}
/**
 * Represents a card object.
 */
interface Card {
    CardKey: number;
    CardNumber: string;
    IsProgrammable: boolean;
    status: string;
    CardTypeCode: string;
    AccountNumber: string;
    AccountId: string;
}
/**
 * Represents the response containing a list of cards.
 */
interface CardResponse {
    data: {
        cards: Card[];
    };
}
/**
 * Represents the response containing code details.
 */
interface CodeResponse {
    data: {
        result: {
            codeId: string;
            code: string;
            createdAt: string;
            updatedAt: string;
            error: null;
        };
    };
}
/**
 * Represents a set of environment variables as key-value pairs.
 */
interface EnvVars {
    [key: string]: string;
}
/**
 * Represents the response containing environment variables.
 */
interface EnvResponse {
    data: {
        result: {
            variables: EnvVars;
            createdAt: string;
            updatedAt: string;
            error: null;
        };
    };
}
/**
 * Represents the result of a code execution, including execution items and errors.
 */
interface ExecutionResult {
    data: {
        result: {
            executionItems: ExecutionItem[];
            error: null;
        };
    };
}
/**
 * Represents the result of executing code, containing execution items.
 */
interface ExecuteResult {
    data: {
        result: ExecutionItem[];
    };
}
/**
 * Represents the response for toggling code features.
 */
interface CodeToggle {
    data: {
        result: {
            Enabled: boolean;
        };
    };
}
/**
 * Represents a single execution item in a code execution result.
 */
interface ExecutionItem {
    executionId: string;
    rootCodeFunctionId: string;
    sandbox: boolean;
    type: string;
    authorizationApproved: boolean | null;
    logs: any[];
    smsCount: number;
    emailCount: number;
    pushNotificationCount: number;
    createdAt: string;
    startedAt: string;
    completedAt: string;
    updatedAt: string;
}
/**
 * Represents a transaction object for code execution.
 */
interface Transaction {
    accountNumber: string;
    dateTime: string;
    centsAmount: number;
    currencyCode: string;
    type: string;
    reference: string;
    card: {
        id: string;
    };
    merchant: Merchant;
}
/**
 * Represents a merchant involved in a transaction.
 */
interface Merchant {
    category: MerchantCategory;
    name: string;
    city: string;
    country: Country;
}
/**
 * Represents a merchant category.
 */
interface MerchantCategory {
    key: string;
    code: string;
    name: string;
}
/**
 * Represents a country object.
 */
interface Country {
    code: CountryCode;
    alpha3: string;
    name: string;
}
/**
 * Enum of supported country codes.
 */
declare enum CountryCode {
    AF = "AF",
    AL = "AL",
    DZ = "DZ",
    AS = "AS",
    AD = "AD",
    AO = "AO",
    AI = "AI",
    AQ = "AQ",
    AG = "AG",
    AR = "AR",
    AM = "AM",
    AW = "AW",
    AU = "AU",
    AT = "AT",
    AZ = "AZ",
    BS = "BS",
    BH = "BH",
    BD = "BD",
    BB = "BB",
    BY = "BY",
    BE = "BE",
    BZ = "BZ",
    BJ = "BJ",
    BM = "BM",
    BT = "BT",
    BO = "BO",
    BQ = "BQ",
    BA = "BA",
    BW = "BW",
    BV = "BV",
    BR = "BR",
    IO = "IO",
    BN = "BN",
    BG = "BG",
    BF = "BF",
    BI = "BI",
    CV = "CV",
    KH = "KH",
    CM = "CM",
    CA = "CA",
    KY = "KY",
    CF = "CF",
    TD = "TD",
    CL = "CL",
    CN = "CN",
    CX = "CX",
    CC = "CC",
    CO = "CO",
    KM = "KM",
    CD = "CD",
    CG = "CG",
    CK = "CK",
    CR = "CR",
    HR = "HR",
    CU = "CU",
    CW = "CW",
    CY = "CY",
    CZ = "CZ",
    CI = "CI",
    DK = "DK",
    DJ = "DJ",
    DM = "DM",
    DO = "DO",
    EC = "EC",
    EG = "EG",
    SV = "SV",
    GQ = "GQ",
    ER = "ER",
    EE = "EE",
    SZ = "SZ",
    ET = "ET",
    FK = "FK",
    FO = "FO",
    FJ = "FJ",
    FI = "FI",
    FR = "FR",
    GF = "GF",
    PF = "PF",
    TF = "TF",
    GA = "GA",
    GM = "GM",
    GE = "GE",
    DE = "DE",
    GH = "GH",
    GI = "GI",
    GR = "GR",
    GL = "GL",
    GD = "GD",
    GP = "GP",
    GU = "GU",
    GT = "GT",
    GG = "GG",
    GN = "GN",
    GW = "GW",
    GY = "GY",
    HT = "HT",
    HM = "HM",
    VA = "VA",
    HN = "HN",
    HK = "HK",
    HU = "HU",
    IS = "IS",
    IN = "IN",
    ID = "ID",
    IR = "IR",
    IQ = "IQ",
    IE = "IE",
    IM = "IM",
    IL = "IL",
    IT = "IT",
    JM = "JM",
    JP = "JP",
    JE = "JE",
    JO = "JO",
    KZ = "KZ",
    KE = "KE",
    KI = "KI",
    KP = "KP",
    KR = "KR",
    KW = "KW",
    KG = "KG",
    LA = "LA",
    LV = "LV",
    LB = "LB",
    LS = "LS",
    LR = "LR",
    LY = "LY",
    LI = "LI",
    LT = "LT",
    LU = "LU",
    MO = "MO",
    MG = "MG",
    MW = "MW",
    MY = "MY",
    MV = "MV",
    ML = "ML",
    MT = "MT",
    MH = "MH",
    MQ = "MQ",
    MR = "MR",
    MU = "MU",
    YT = "YT",
    MX = "MX",
    FM = "FM",
    MD = "MD",
    MC = "MC",
    MN = "MN",
    ME = "ME",
    MS = "MS",
    MA = "MA",
    MZ = "MZ",
    MM = "MM",
    NA = "NA",
    NR = "NR",
    NP = "NP",
    NL = "NL",
    NC = "NC",
    NZ = "NZ",
    NI = "NI",
    NE = "NE",
    NG = "NG",
    NU = "NU",
    NF = "NF",
    MP = "MP",
    NO = "NO",
    OM = "OM",
    PK = "PK",
    PW = "PW",
    PS = "PS",
    PA = "PA",
    PG = "PG",
    PY = "PY",
    PE = "PE",
    PH = "PH",
    PN = "PN",
    PL = "PL",
    PT = "PT",
    PR = "PR",
    QA = "QA",
    MK = "MK",
    RO = "RO",
    RU = "RU",
    RW = "RW",
    RE = "RE",
    BL = "BL",
    SH = "SH",
    KN = "KN",
    LC = "LC",
    MF = "MF",
    PM = "PM",
    VC = "VC",
    WS = "WS",
    SM = "SM",
    ST = "ST",
    SA = "SA",
    SN = "SN",
    RS = "RS",
    SC = "SC",
    SL = "SL",
    SG = "SG",
    SX = "SX",
    SK = "SK",
    SI = "SI",
    SB = "SB",
    SO = "SO",
    ZA = "ZA",
    GS = "GS",
    SS = "SS",
    ES = "ES",
    LK = "LK",
    SD = "SD",
    SR = "SR",
    SJ = "SJ",
    SE = "SE",
    CH = "CH",
    SY = "SY",
    TW = "TW",
    TJ = "TJ",
    TZ = "TZ",
    TH = "TH",
    TL = "TL",
    TG = "TG",
    TK = "TK",
    TO = "TO",
    TT = "TT",
    TN = "TN",
    TR = "TR",
    TM = "TM",
    TC = "TC",
    TV = "TV",
    UG = "UG",
    UA = "UA",
    AE = "AE",
    GB = "GB",
    UM = "UM",
    US = "US",
    UY = "UY",
    UZ = "UZ",
    VU = "VU",
    VE = "VE",
    VN = "VN",
    VG = "VG",
    VI = "VI",
    WF = "WF",
    EH = "EH",
    YE = "YE",
    ZM = "ZM",
    ZW = "ZW",
    AX = "AX",
    ZZ = "ZZ"
}

/**
 * Main API class for interacting with Investec programmable cards.
 *
 * Example usage:
 * ```typescript
 * import { InvestecCardApi } from './investec-card-api';
 * const api = new InvestecCardApi('clientId', 'clientSecret', 'apiKey');
 * const cards = await api.getCards();
 * ```
 *
 * @remarks
 * - All methods throw on HTTP/network errors.
 * - All methods return typed responses.
 * - You must provide valid Investec API credentials.
 */
declare class InvestecCardApi {
    /** The API host URL. */
    host: string;
    /** The OAuth client ID. */
    clientId: string;
    /** The OAuth client secret. */
    clientSecret: string;
    /** The Investec API key. */
    apiKey: string;
    /** The current OAuth token. */
    token: string;
    /** The token expiry date. */
    expiresIn: Date;
    /**
     * Constructs a new InvestecCardApi instance.
     * @param clientId - OAuth client ID
     * @param clientSecret - OAuth client secret
     * @param apiKey - Investec API key
     * @param host - API host URL (default: 'https://openapi.investec.com')
     */
    constructor(clientId: string, clientSecret: string, apiKey: string, host?: string);
    /**
     * Gets a valid OAuth token, refreshing if necessary.
     * @returns The OAuth token string.
     * @throws Error if token cannot be retrieved.
     */
    getToken(): Promise<string>;
    /**
     * Requests a new OAuth access token from Investec.
     * @returns The AuthResponse object.
     * @throws Error if authentication fails or the cards scope is missing.
     */
    getAccessToken(): Promise<AuthResponse>;
    /**
     * Uploads environment variables to a programmable card.
     * @param cardKey - The card key
     * @param env - The environment variables object
     * @returns The EnvResponse object
     * @throws Error if parameters are missing or the request fails.
     */
    uploadEnv(cardKey: number, env: object): Promise<EnvResponse>;
    /**
     * Uploads code to a programmable card.
     * @param cardKey - The card key
     * @param code - The code object
     * @returns The CodeResponse object
     * @throws Error if parameters are missing or the request fails.
     */
    uploadCode(cardKey: number, code: object): Promise<CodeResponse>;
    /**
     * Publishes code to a programmable card.
     * @param cardKey - The card key
     * @param codeId - The code ID
     * @param code - The code string
     * @returns The CodeResponse object
     * @throws Error if parameters are missing or the request fails.
     */
    uploadPublishedCode(cardKey: number, codeId: string, code: string): Promise<CodeResponse>;
    /**
     * Retrieves all programmable cards for the authenticated user.
     * @returns The CardResponse object
     * @throws Error if the request fails.
     */
    getCards(): Promise<CardResponse>;
    /**
     * Retrieves environment variables for a programmable card.
     * @param cardKey - The card key
     * @returns The EnvResponse object
     * @throws Error if parameters are missing or the request fails.
     */
    getEnv(cardKey: number): Promise<EnvResponse>;
    /**
     * Retrieves code for a programmable card.
     * @param cardKey - The card key
     * @returns The CodeResponse object
     * @throws Error if parameters are missing or the request fails.
     */
    getCode(cardKey: number): Promise<CodeResponse>;
    /**
     * Retrieves published code for a programmable card.
     * @param cardKey - The card key
     * @returns The CodeResponse object
     * @throws Error if parameters are missing or the request fails.
     */
    getPublishedCode(cardKey: number): Promise<CodeResponse>;
    /**
     * Enables or disables programmable features on a card.
     * @param cardKey - The card key
     * @param enabled - Whether to enable the feature
     * @returns The CodeToggle object
     * @throws Error if parameters are missing or the request fails.
     */
    toggleCode(cardKey: number, enabled: boolean): Promise<CodeToggle>;
    /**
     * Retrieves code execution results for a programmable card.
     * @param cardKey - The card key
     * @returns The ExecutionResult object
     * @throws Error if parameters are missing or the request fails.
     */
    getExecutions(cardKey: number): Promise<ExecutionResult>;
    /**
     * Executes code in a simulated transaction context.
     * @param code - The code string
     * @param transaction - The transaction object
     * @param cardKey - The card key
     * @returns The ExecuteResult object
     * @throws Error if parameters are missing or the request fails.
     */
    executeCode(code: string, transaction: Transaction, cardKey: number): Promise<ExecuteResult>;
    /**
     * Retrieves supported currencies for programmable cards.
     * @returns The ReferenceResponse object
     * @throws Error if the request fails.
     */
    getCurrencies(): Promise<ReferenceResponse>;
    /**
     * Retrieves supported countries for programmable cards.
     * @returns The ReferenceResponse object
     * @throws Error if the request fails.
     */
    getCountries(): Promise<ReferenceResponse>;
    /**
     * Retrieves supported merchants for programmable cards.
     * @returns The ReferenceResponse object
     * @throws Error if the request fails.
     */
    getMerchants(): Promise<ReferenceResponse>;
}

export { type AuthResponse, type CardResponse, type CodeResponse, type CodeToggle, type EnvResponse, type ExecuteResult, type ExecutionResult, InvestecCardApi, type ReferenceResponse, type Transaction };