@syscli/oneclickdz 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,730 @@
+type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/** A fetch implementation compatible with the platform global. */
+type FetchLike = typeof globalThis.fetch;
+interface RetryConfig {
+    /** Total attempts including the first. 1 disables retrying. */
+    attempts: number;
+    /** Wait the Retry-After header when the API sends one. */
+    respectRetryAfter: boolean;
+}
+/** Page numbers and totals the API returns on list endpoints. */
+interface Pagination {
+    page: number;
+    pageSize: number;
+    totalPages: number;
+    totalResults: number;
+}
+interface ResponseMeta {
+    timestamp?: string;
+    pagination?: Pagination;
+    [key: string]: unknown;
+}
+/**
+ * The success envelope every endpoint returns. `data` is the endpoint payload;
+ * a few endpoints (the gift-card catalog, for one) hang extra counts off the top
+ * level, so unknown keys are preserved.
+ */
+interface Envelope<T> {
+    success: true;
+    data: T;
+    meta?: ResponseMeta;
+    requestId?: string;
+    [key: string]: unknown;
+}
+type QueryValue = string | number | boolean | null | undefined;
+type QueryParams = Record<string, QueryValue>;
+interface HttpClientConfig {
+    /** The API access token, sent as the X-Access-Token header. */
+    key: string;
+    /** Trailing slash is optional; it is added if missing. */
+    baseUrl: string;
+    fetch: FetchLike;
+    timeoutMs: number;
+    retry: RetryConfig;
+}
+interface RequestOptions {
+    query?: QueryParams;
+    /** Serialized as JSON. Its presence is what adds the Content-Type header. */
+    body?: unknown;
+    /** Caller cancellation, merged with the per-request timeout. */
+    signal?: AbortSignal;
+}
+declare class HttpClient {
+    private readonly config;
+    constructor(config: HttpClientConfig);
+    /**
+     * Send a request and return the unwrapped envelope.
+     *
+     * Retry policy is deliberately narrow. A 429 is always safe to retry, since
+     * the request was rejected before processing. A 5xx or a dropped connection is
+     * retried only for GET: a send that timed out may still have gone through, and
+     * a blind retry could charge the account twice. Use a `ref` for safe resends.
+     */
+    request<T>(method: HttpMethod, path: string, options?: RequestOptions): Promise<Envelope<T>>;
+    private retryable;
+    /** Wait the API's Retry-After when offered, otherwise an exponential backoff. */
+    private backoffMs;
+    private send;
+    /** Confirm the body is a success envelope before handing it back. */
+    private toEnvelope;
+}
+
+/**
+ * One page of a list, plus a `next()` that fetches the page after it. `next()`
+ * resolves to undefined once there is nothing more, so a `while (page)` loop ends
+ * cleanly.
+ */
+interface Page<T> extends Pagination {
+    items: T[];
+    /** True while a further page exists. */
+    hasMore: boolean;
+    /** The next page, or undefined when this is the last one. */
+    next(): Promise<Page<T> | undefined>;
+}
+declare abstract class Resource {
+    protected readonly http: HttpClient;
+    constructor(http: HttpClient);
+    /** GET a path and return its `data` payload. */
+    protected getData<T>(path: string, query?: QueryParams, signal?: AbortSignal): Promise<T>;
+    /** POST a body and return the `data` payload. */
+    protected postData<T>(path: string, body: unknown, signal?: AbortSignal): Promise<T>;
+    /**
+     * Fetch one page of a list. `extract` pulls the items and the pagination block
+     * out of whatever shape the endpoint nests them in; it gets the whole envelope
+     * because some endpoints keep pagination in `data` and others in `meta`.
+     * `next()` reissues the same request with the page number bumped.
+     */
+    protected fetchPage<T>(path: string, query: QueryParams, extract: (env: Envelope<unknown>) => {
+        items: T[];
+        pagination: Pagination;
+    }): Promise<Page<T>>;
+    /** Walk every item across every page, starting from a first-page promise. */
+    protected iterate<T>(first: Promise<Page<T>>): AsyncGenerator<T>;
+}
+
+/**
+ * Where a mobile or internet top-up sits in its lifecycle. PENDING and HANDLING
+ * are in-flight; the rest are final. QUEUED only appears for internet orders.
+ * UNKNOWN_ERROR means the outcome is undecided and can still settle within 24h,
+ * which is why a top-up should not be treated as failed the moment it shows up.
+ */
+type TopupStatus = "PENDING" | "HANDLING" | "QUEUED" | "FULFILLED" | "REFUNDED" | "UNKNOWN_ERROR";
+/** A gift-card order's lifecycle. PARTIALLY_FILLED means some cards came through. */
+type GiftOrderStatus = "HANDLING" | "FULFILLED" | "PARTIALLY_FILLED" | "REFUNDED";
+/** A Navio payment link's lifecycle. */
+type PaymentStatus = "PENDING" | "CONFIRMED" | "FAILED";
+/** The top-up statuses at which polling stops. */
+declare const TOPUP_TERMINAL: readonly TopupStatus[];
+/** The gift-card order statuses at which polling stops. */
+declare const GIFT_TERMINAL: readonly GiftOrderStatus[];
+/** The payment statuses at which polling stops. */
+declare const PAYMENT_TERMINAL: readonly PaymentStatus[];
+type KeyType = "SANDBOX" | "PRODUCTION";
+type KeyScope = "READ-WRITE" | "READ-ONLY";
+interface ApiKeyInfo {
+    key: string;
+    isEnabled: boolean;
+    type: KeyType;
+    /** Allowed source IPs. An empty array means any IP is accepted. */
+    allowedips: string[];
+    scope: KeyScope;
+}
+/** What `validate()` returns: the account name and the key's own settings. */
+interface ValidateResult {
+    username: string;
+    apiKey: ApiKeyInfo;
+}
+/** What `ping()` returns: the API's own status and each operator's reachability. */
+interface ServiceHealth {
+    api: string;
+    operators: Record<string, string>;
+}
+interface Balance {
+    /** Current account balance in dinars. */
+    balance: number;
+}
+interface Transaction {
+    _id: string;
+    /** The kind of movement, such as a top-up or a deposit. */
+    type: string;
+    /** The direction of the movement: increment or decrement. */
+    operation: string;
+    amount: number;
+    oldBalance: number;
+    newBalance: number;
+    /** The id of the related order, when there is one. */
+    objid: string;
+    note: string;
+    time: string;
+}
+interface TransactionsParams {
+    page?: number;
+    pageSize?: number;
+    /** ISO 8601 start of the date filter. Pass `to` alongside it. */
+    from?: string;
+    /** ISO 8601 end of the date filter. Pass `from` alongside it. */
+    to?: string;
+}
+/** A paginated `{ items, pagination }` payload, the shape list endpoints return. */
+interface ItemsPage<T> {
+    items: T[];
+    pagination: Pagination;
+}
+
+declare class Core extends Resource {
+    /** Check the API and each operator's reachability. */
+    ping(signal?: AbortSignal): Promise<ServiceHealth>;
+    /** Confirm the key and read its environment, scope, and IP allowlist. */
+    validate(signal?: AbortSignal): Promise<ValidateResult>;
+}
+
+declare class Account extends Resource {
+    /** The current balance in dinars. */
+    balance(signal?: AbortSignal): Promise<Balance>;
+    /** One page of the transaction ledger, newest first. */
+    transactions(params?: TransactionsParams): Promise<Page<Transaction>>;
+    /** Every transaction across every page, as an async iterator. */
+    paginateTransactions(params?: TransactionsParams): AsyncGenerator<Transaction>;
+}
+
+/**
+ * The machine-readable error codes. The API's own codes are kept verbatim so
+ * `error.code` matches what the docs list. `network` is the one code the client
+ * adds itself, for a request that never reached the server.
+ */
+type OneClickErrorCode = "MISSING_ACCESS_TOKEN" | "INVALID_ACCESS_TOKEN" | "ERR_AUTH" | "NO_BALANCE" | "INSUFFICIENT_BALANCE" | "DUPLICATED_REF" | "IP_BLOCKED" | "IP_NOT_ALLOWED" | "ERR_VALIDATION" | "ERR_PHONE" | "ERR_STOCK" | "NOT_FOUND" | "RATE_LIMIT_EXCEEDED" | "INTERNAL_SERVER_ERROR" | "INTERNAL_ERROR" | "ERR_SERVICE" | "network" | (string & {});
+interface OneClickErrorOptions {
+    status?: number;
+    /** The `error.details` object the API attaches to some failures. */
+    details?: unknown;
+    /** The request id from the envelope, handy when opening a support ticket. */
+    requestId?: string;
+    /** The full parsed response body, kept so callers can read everything. */
+    body?: unknown;
+    cause?: unknown;
+}
+declare class OneClickError extends Error {
+    /** HTTP status, or undefined for a client-side or network error. */
+    readonly status?: number;
+    readonly code: OneClickErrorCode;
+    readonly details: unknown;
+    readonly requestId?: string;
+    readonly body: unknown;
+    constructor(message: string, code: OneClickErrorCode, options?: OneClickErrorOptions);
+}
+/** 401. The key is missing, malformed, or rejected. */
+declare class AuthError extends OneClickError {
+}
+/**
+ * 403. The key is valid but the action is not allowed: a blocked or unlisted IP,
+ * for instance. Balance and duplicate-ref cases have their own subclasses below
+ * so they can be caught on their own.
+ */
+declare class ForbiddenError extends OneClickError {
+}
+/** 403 with NO_BALANCE or INSUFFICIENT_BALANCE. Top up the account first. */
+declare class InsufficientBalanceError extends ForbiddenError {
+}
+/**
+ * 403 with DUPLICATED_REF. The reference was already used, so the original order
+ * stands and nothing was charged twice. Look the first one up by its ref rather
+ * than sending again.
+ */
+declare class DuplicateRefError extends ForbiddenError {
+}
+interface ValidationIssue {
+    field: string;
+    message: string;
+    /** The order reference this issue belongs to, when checking a batch. */
+    ref?: string;
+}
+interface ValidationErrorOptions extends OneClickErrorOptions {
+    /** The API code for a server-side 400; defaults to ERR_VALIDATION. */
+    code?: OneClickErrorCode;
+    /** Filled when the client caught the problem before sending. */
+    issues?: ValidationIssue[];
+}
+/**
+ * A 400 from the API, or a client-side check. `issues` is filled when the client
+ * caught the problem before sending; for a server 400 it is empty and the detail
+ * sits in `code`, `message`, and `details`.
+ */
+declare class ValidationError extends OneClickError {
+    readonly issues: ValidationIssue[];
+    constructor(message: string, options?: ValidationErrorOptions);
+}
+/** 404. No order, product, or payment matches the id or reference. */
+declare class NotFoundError extends OneClickError {
+}
+interface RateLimitErrorOptions extends OneClickErrorOptions {
+    /** Seconds to wait before retrying, read from the Retry-After header. */
+    retryAfter?: number;
+}
+/** 429. Too many requests inside the per-minute window. */
+declare class RateLimitError extends OneClickError {
+    readonly retryAfter?: number;
+    constructor(message: string, options?: RateLimitErrorOptions);
+}
+/**
+ * 500 or 503. The request may or may not have been processed. For a top-up this
+ * matters: the docs say not to refund a server error for 24 hours, since the
+ * recharge can still settle. The client never auto-retries a send on a 5xx for
+ * the same reason.
+ */
+declare class ServiceError extends OneClickError {
+}
+/** The request never reached the server: DNS, socket, or a timeout abort. */
+declare class NetworkError extends OneClickError {
+    constructor(message: string, options?: OneClickErrorOptions);
+}
+/** Any other 4xx the client does not model on its own. */
+declare class RequestError extends OneClickError {
+}
+/**
+ * Build the right error from a failed envelope. The API's `error.code` decides
+ * the class where we recognise it; otherwise the HTTP status does. The code is
+ * passed through verbatim so `error.code` matches the documentation.
+ */
+declare function errorFromResponse(status: number, body: unknown, retryAfter?: number): OneClickError;
+
+interface PollOptions {
+    /** Milliseconds between checks. The docs recommend a fixed 5s. */
+    intervalMs?: number;
+    /** How many checks before giving up. */
+    maxAttempts?: number;
+    /** Cancel the wait early. The pending delay rejects at once when aborted. */
+    signal?: AbortSignal;
+}
+/** Raised when a status never reaches a terminal state within the attempt budget. */
+declare class PollTimeoutError extends OneClickError {
+    /** The most recent value seen before time ran out. */
+    readonly last: unknown;
+    constructor(message: string, last: unknown, attempts: number);
+}
+/**
+ * Call `fetchOnce` until `isDone` accepts the result, then return that result.
+ * The first check happens immediately; the interval only applies between checks,
+ * so a status that is already settled returns without an extra wait.
+ */
+declare function pollUntil<T>(fetchOnce: () => Promise<T>, isDone: (value: T) => boolean, options?: PollOptions): Promise<T>;
+
+interface MobilePlanBase {
+    code: string;
+    name: string;
+    operator: string;
+    /**
+     * Your wholesale cost factor. Absent on the wholesale `GROS_*` plans. Do not
+     * show it to end users; apply your own markup.
+     */
+    cost?: number;
+    isEnabled: boolean;
+}
+/** A plan whose amount you choose, within a range. */
+interface DynamicMobilePlan extends MobilePlanBase {
+    min_amount: number;
+    max_amount: number;
+}
+/** A plan with a fixed amount, such as a data pack. */
+interface FixedMobilePlan extends MobilePlanBase {
+    amount: number;
+}
+interface MobilePlans {
+    dynamicPlans: DynamicMobilePlan[];
+    fixedPlans: FixedMobilePlan[];
+}
+interface MobileSendInput {
+    /** A plan code from `plans()`, such as `PREPAID_DJEZZY`. */
+    plan_code: string;
+    /** The recipient number: ten digits starting 05, 06, or 07. */
+    MSSIDN: string;
+    /** Required for dynamic plans, within the plan's min and max. */
+    amount?: number;
+    /** Your order reference. One is generated when omitted. */
+    ref?: string;
+}
+interface MobileSendResult {
+    topupId: string;
+    topupRef: string;
+}
+/** A retry the API suggests after a refund. */
+interface SuggestedOffer {
+    typename: string;
+    plan_code: string;
+    amount: number;
+}
+interface MobileTopup {
+    _id: string;
+    ref?: string;
+    status: TopupStatus;
+    plan_code: string;
+    MSSIDN: string;
+    topup_amount: number;
+    balance_amount: number;
+    created_at: string;
+    /** Present on a REFUNDED order, explaining why it did not go through. */
+    refund_message?: string;
+    /** Alternative offers to try after a refund. */
+    suggested_offers?: SuggestedOffer[];
+    follow_orderid?: string;
+    retry_orderid?: string;
+}
+interface MobileListParams {
+    page?: number;
+    pageSize?: number;
+    from?: string;
+    to?: string;
+}
+declare class Mobile extends Resource {
+    /** The plans available to your account, split into dynamic and fixed. */
+    plans(signal?: AbortSignal): Promise<MobilePlans>;
+    /**
+     * Send a top-up. The number and amount are checked first, and a reference is
+     * generated when you do not pass one, so the returned `topupRef` is always set.
+     */
+    send(input: MobileSendInput, signal?: AbortSignal): Promise<MobileSendResult>;
+    /** Look a top-up up by your own reference. */
+    checkByRef(ref: string, signal?: AbortSignal): Promise<MobileTopup>;
+    /** Look a top-up up by the id from `send`. */
+    checkById(id: string, signal?: AbortSignal): Promise<MobileTopup>;
+    /**
+     * Send a top-up and wait for it to settle, polling by reference. Resolves with
+     * the final top-up once it is FULFILLED, REFUNDED, or UNKNOWN_ERROR. Defaults
+     * to a check every 5 seconds for up to 5 minutes, which the docs recommend.
+     */
+    sendAndWait(input: MobileSendInput, options?: PollOptions): Promise<MobileTopup>;
+    /** One page of your past top-ups, newest first. */
+    list(params?: MobileListParams): Promise<Page<MobileTopup>>;
+    /** Every past top-up across every page, as an async iterator. */
+    paginate(params?: MobileListParams): AsyncGenerator<MobileTopup>;
+}
+
+declare const INSPECT: unique symbol;
+declare class Secret<T = string> {
+    #private;
+    constructor(value: T);
+    /** The real value. Calling this is the deliberate, searchable moment a secret is read. */
+    reveal(): T;
+    /** Used by JSON.stringify, so a secret nested in an object serializes redacted. */
+    toJSON(): string;
+    toString(): string;
+    [INSPECT](): string;
+    static of<T>(value: T): Secret<T>;
+}
+declare function isSecret(value: unknown): value is Secret<unknown>;
+/** Reveal a value whether or not it is wrapped, for code that handles both. */
+declare function reveal<T>(value: Secret<T> | T): T;
+
+type InternetType = "ADSL" | "4G";
+interface InternetProduct {
+    /** Your wholesale cost. Strip this before showing products to end users. */
+    cost: number;
+    /** The card's face value in dinars. */
+    value: number;
+    available: boolean;
+}
+interface InternetProducts {
+    products: InternetProduct[];
+    type: string;
+}
+interface NumberCheck {
+    /** The masked client identifier the API returns for a valid line. */
+    ncli: string;
+    type: string;
+    /** The current offer, for ADSL lines. */
+    offre?: string;
+}
+interface InternetSendInput {
+    type: InternetType;
+    /** ADSL: nine digits starting 0. 4G: 213 followed by nine digits. */
+    number: string;
+    /** A face value from `products()`. */
+    value: number;
+    /** Your order reference. One is generated when omitted. */
+    ref?: string;
+}
+interface InternetSendResult {
+    topupId: string;
+    topupRef: string;
+}
+interface InternetTopup {
+    _id: string;
+    ref?: string;
+    status: TopupStatus;
+    type: string;
+    number: string;
+    topup_amount: number;
+    /** The recharge code, present once FULFILLED. Call `.reveal()` to read it. */
+    card_code?: Secret<string>;
+    num_trans?: string;
+    date_traitement?: string;
+    created_at: string;
+}
+interface InternetListParams {
+    page?: number;
+    pageSize?: number;
+    from?: string;
+    to?: string;
+}
+declare class Internet extends Resource {
+    /** The cards on offer for a service type, with their cost and stock. */
+    products(type: InternetType, signal?: AbortSignal): Promise<InternetProducts>;
+    /** Confirm a number is valid and active before sending to it. */
+    checkNumber(type: InternetType, number: string, signal?: AbortSignal): Promise<NumberCheck>;
+    /** Send a recharge. The number and value are checked first; a ref is filled in. */
+    send(input: InternetSendInput, signal?: AbortSignal): Promise<InternetSendResult>;
+    checkByRef(ref: string, signal?: AbortSignal): Promise<InternetTopup>;
+    checkById(id: string, signal?: AbortSignal): Promise<InternetTopup>;
+    /**
+     * Send and wait for the recharge to settle. Resolves with the final order,
+     * its `card_code` ready to reveal once FULFILLED. A QUEUED order can take up to
+     * 48 hours, well past the default polling window, so expect a timeout there.
+     */
+    sendAndWait(input: InternetSendInput, options?: PollOptions): Promise<InternetTopup>;
+    list(params?: InternetListParams): Promise<Page<InternetTopup>>;
+    paginate(params?: InternetListParams): AsyncGenerator<InternetTopup>;
+}
+
+interface GiftProductSummary {
+    id: string;
+    title: string;
+    enabled: boolean;
+    /** The region the product is valid in, such as france or turkey. Absent on some products. */
+    region?: string;
+}
+interface GiftCategory {
+    title: string;
+    products: GiftProductSummary[];
+}
+interface GiftCatalog {
+    categories: GiftCategory[];
+    totalCategories?: number;
+    totalProducts?: number;
+}
+interface GiftProductType {
+    id: string;
+    /** The denomination label, such as "PSN 500 DA". */
+    name: string;
+    /** Your wholesale price. Do not show it to end users. */
+    price: number;
+    /** Stock on hand. Zero means out of stock. */
+    quantity: number;
+}
+interface GiftProductDetails {
+    productId: string;
+    productTitle: string;
+    types: GiftProductType[];
+}
+interface GiftOrderInput {
+    /** A product id from the catalog. */
+    productId: string;
+    /** A type id from `checkProduct`. */
+    typeId: string;
+    /** How many cards to buy. At least one. */
+    quantity: number;
+}
+interface GiftOrderResult {
+    orderId: string;
+}
+/** A delivered card. Both fields are secrets; call `.reveal()` to read them. */
+interface GiftCard {
+    value: Secret<string>;
+    serial: Secret<string>;
+}
+interface GiftOrder {
+    status: GiftOrderStatus;
+    quantity: number;
+    fulfilled_quantity: number;
+    fulfilled_amount: number;
+    price_per_card: number;
+    /** Filled once the order is FULFILLED or PARTIALLY_FILLED. */
+    cards: GiftCard[];
+    /** Present in the order list; the single-order check omits these. */
+    _id?: string;
+    product?: string;
+    type?: string;
+    time?: string;
+}
+interface GiftOrdersParams {
+    page?: number;
+    pageSize?: number;
+    from?: string;
+    to?: string;
+}
+declare class GiftCards extends Resource {
+    /** The full product catalog. Cache it; the docs say it changes rarely. */
+    catalog(signal?: AbortSignal): Promise<GiftCatalog>;
+    /** A product's denominations, with live pricing and stock. */
+    checkProduct(productId: string, signal?: AbortSignal): Promise<GiftProductDetails>;
+    /** Place an order. The product, type, and quantity are checked first. */
+    placeOrder(input: GiftOrderInput, signal?: AbortSignal): Promise<GiftOrderResult>;
+    /** Read an order's status and, once settled, its cards. */
+    checkOrder(orderId: string, signal?: AbortSignal): Promise<GiftOrder>;
+    /**
+     * Place an order and wait for it to settle. Resolves once the order is
+     * FULFILLED, PARTIALLY_FILLED, or REFUNDED. Gift cards can take longer than a
+     * top-up, so this checks every 5 seconds for up to 10 minutes by default.
+     */
+    placeOrderAndWait(input: GiftOrderInput, options?: PollOptions): Promise<GiftOrder>;
+    /** One page of past orders, newest first. */
+    listOrders(params?: GiftOrdersParams): Promise<Page<GiftOrder>>;
+    /** Every past order across every page, as an async iterator. */
+    paginateOrders(params?: GiftOrdersParams): AsyncGenerator<GiftOrder>;
+}
+
+/** Who pays the gateway fee. NO_FEE is the default. */
+type FeeMode = "NO_FEE" | "SPLIT_FEE" | "CUSTOMER_FEE";
+declare const MIN_PAYMENT_AMOUNT = 500;
+declare const MAX_PAYMENT_AMOUNT = 500000;
+interface PaymentProductInfo {
+    /** What the customer is paying for. One to two hundred characters. */
+    title: string;
+    /** Optional details, up to a thousand characters. Markdown is allowed. */
+    description?: string;
+    /** Amount in dinars: a whole number from 500 to 500000. */
+    amount: number;
+}
+interface CreateLinkInput {
+    productInfo: PaymentProductInfo;
+    feeMode?: FeeMode;
+    /** Shown to the customer after a successful payment, up to 500 characters. */
+    successMessage?: string;
+    /** Where to send the customer after payment. Must be http or https. */
+    redirectUrl?: string;
+}
+interface PaymentLink {
+    uid: string;
+    ref: string;
+    isSandbox: boolean;
+    productInfo: PaymentProductInfo;
+    feeMode: FeeMode;
+    successMessage?: string;
+    redirectUrl?: string;
+    time: string;
+}
+interface CreateLinkResult {
+    paymentLink: PaymentLink;
+    /** The URL to send the customer to. */
+    paymentUrl: string;
+    /** The reference to poll with `checkPayment`. */
+    paymentRef: string;
+}
+interface PaymentTransactionDetails {
+    amount: number;
+    currency: string;
+    isSandbox: boolean;
+    createdDate: string;
+}
+interface PaymentCheck {
+    status: PaymentStatus;
+    message: string;
+    paymentRef: string;
+    transactionDetails: PaymentTransactionDetails;
+}
+declare class Payments extends Resource {
+    /** Create a payment link. Returns the URL to send the customer to. */
+    createLink(input: CreateLinkInput, signal?: AbortSignal): Promise<CreateLinkResult>;
+    /** Check a payment's status by its reference. */
+    checkPayment(ref: string, signal?: AbortSignal): Promise<PaymentCheck>;
+    /**
+     * Poll a payment until it is CONFIRMED or FAILED. The default window is twenty
+     * minutes, matching how long an unpaid link stays open; a payment that is
+     * never started times out with a PollTimeoutError. Pass a signal to stop early.
+     */
+    waitForPayment(ref: string, options?: PollOptions): Promise<PaymentCheck>;
+}
+
+interface OneClickDZOptions {
+    /** Your access token, sandbox or production, from the dashboard. */
+    key: string;
+    /** Defaults to the production v3 endpoint. */
+    baseUrl?: string;
+    /** Per-request timeout in milliseconds. Defaults to 30000. */
+    timeoutMs?: number;
+    /** Override either retry field; the rest keep their defaults. */
+    retry?: Partial<RetryConfig>;
+    /** Supply a fetch for older runtimes or for tests. Defaults to the global. */
+    fetch?: FetchLike;
+}
+declare class OneClickDZ {
+    readonly core: Core;
+    readonly account: Account;
+    readonly mobile: Mobile;
+    readonly internet: Internet;
+    readonly giftCards: GiftCards;
+    readonly payments: Payments;
+    private readonly http;
+    constructor(options: OneClickDZOptions);
+    /** Shortcut for `core.ping()`: the API and operator status. */
+    ping(signal?: AbortSignal): Promise<ServiceHealth>;
+    /** Shortcut for `core.validate()`: confirm the key and read its environment. */
+    validate(signal?: AbortSignal): Promise<ValidateResult>;
+}
+
+/** Mobile MSISDN: Mobilis, Djezzy, or Ooredoo, ten digits starting 05, 06, or 07. */
+declare const MOBILE_NUMBER: RegExp;
+/** ADSL line number: nine digits starting with 0. */
+declare const ADSL_NUMBER: RegExp;
+/** 4G number: the 213 country code followed by nine digits. */
+declare const FOURG_NUMBER: RegExp;
+declare function isMobileNumber(value: string): boolean;
+declare function isAdslNumber(value: string): boolean;
+declare function isFourgNumber(value: string): boolean;
+/** A whole number of dinars, at or above one. The API has no fractional amounts. */
+declare function isWholeAmount(value: unknown): value is number;
+/**
+ * Gathers field problems and turns them into one ValidationError. Using a
+ * collector rather than throwing on the first issue means a caller sees every
+ * problem with an input at once.
+ */
+declare class Issues {
+    private readonly list;
+    /** Record a problem. The ref ties an issue to one order when checking a batch. */
+    add(field: string, message: string, ref?: string): this;
+    /** Record a problem only when the condition holds. */
+    addIf(condition: boolean, field: string, message: string, ref?: string): this;
+    get any(): boolean;
+    all(): ValidationIssue[];
+    /** Throw if anything was collected; otherwise do nothing. */
+    throwIfAny(summary?: string): void;
+}
+/** A required string field that must be present and non-empty. */
+declare function requireText(issues: Issues, value: unknown, field: string, ref?: string): void;
+
+/** Build a unique-enough order reference with a readable prefix. */
+declare function generateRef(prefix?: string): string;
+
+/** A markup as a percentage of cost, or a flat number of dinars added on top. */
+type Markup = {
+    percent: number;
+} | {
+    flat: number;
+};
+/** Apply a markup to a wholesale cost and round to a whole dinar. */
+declare function sellPrice(cost: number, markup: Markup): number;
+/** An internet product as a customer should see it: face value, sell price, stock. */
+interface CustomerInternetProduct {
+    value: number;
+    price: number;
+    available: boolean;
+}
+/**
+ * Turn the raw internet products into a customer-facing list. The wholesale
+ * `cost` is dropped and `price` is your sell price for the card's face value.
+ */
+declare function priceInternetProducts(products: InternetProduct[], markup: Markup): CustomerInternetProduct[];
+/** A gift-card denomination as a customer should see it, with cost removed. */
+interface CustomerGiftType {
+    id: string;
+    name: string;
+    price: number;
+    inStock: boolean;
+}
+/**
+ * Turn a product's types into a customer-facing list. The wholesale `price` is
+ * replaced by your sell price, and stock collapses to a single boolean.
+ */
+declare function priceGiftTypes(types: GiftProductType[], markup: Markup): CustomerGiftType[];
+
+declare const VERSION = "0.1.0";
+
+export { ADSL_NUMBER, Account, type ApiKeyInfo, AuthError, type Balance, Core, type CreateLinkInput, type CreateLinkResult, type CustomerGiftType, type CustomerInternetProduct, DuplicateRefError, type DynamicMobilePlan, type Envelope, FOURG_NUMBER, type FeeMode, type FetchLike, type FixedMobilePlan, ForbiddenError, GIFT_TERMINAL, type GiftCard, GiftCards, type GiftCatalog, type GiftCategory, type GiftOrder, type GiftOrderInput, type GiftOrderResult, type GiftOrderStatus, type GiftOrdersParams, type GiftProductDetails, type GiftProductSummary, type GiftProductType, type HttpMethod, InsufficientBalanceError, Internet, type InternetListParams, type InternetProduct, type InternetProducts, type InternetSendInput, type InternetSendResult, type InternetTopup, type InternetType, Issues, type ItemsPage, type KeyScope, type KeyType, MAX_PAYMENT_AMOUNT, MIN_PAYMENT_AMOUNT, MOBILE_NUMBER, type Markup, Mobile, type MobileListParams, type MobilePlans, type MobileSendInput, type MobileSendResult, type MobileTopup, NetworkError, NotFoundError, type NumberCheck, OneClickDZ, type OneClickDZOptions, OneClickError, type OneClickErrorCode, type OneClickErrorOptions, PAYMENT_TERMINAL, type Page, type Pagination, type PaymentCheck, type PaymentLink, type PaymentProductInfo, type PaymentStatus, type PaymentTransactionDetails, Payments, type PollOptions, PollTimeoutError, RateLimitError, type RateLimitErrorOptions, RequestError, type ResponseMeta, type RetryConfig, Secret, ServiceError, type ServiceHealth, type SuggestedOffer, TOPUP_TERMINAL, type TopupStatus, type Transaction, type TransactionsParams, VERSION, type ValidateResult, ValidationError, type ValidationErrorOptions, type ValidationIssue, errorFromResponse, generateRef, isAdslNumber, isFourgNumber, isMobileNumber, isSecret, isWholeAmount, pollUntil, priceGiftTypes, priceInternetProducts, requireText, reveal, sellPrice };