// SPDX-FileCopyrightText: © 2024 LEDGER SAS
// SPDX-License-Identifier: Apache-2.0

import type { CurrencyConfig } from '../config'
import type { CoinModuleApi, Memo, MemoNotSupported, TxData, TxDataNotSupported } from './types'

/**
 * Methods a CoinModuleImpl author may omit when the chain does not support them.
 * The framework's `withDefaults` fills the gaps before the consumer receives the
 * object as a full {@link CoinModuleApi}.
 *
 * Block        — getBlock, getBlockInfo     (many chains throw "not supported")
 * Staking      — getStakes, getRewards,     (à la carte; a module may ship getStakes
 *                getValidators               without getValidators)
 * SmartContract— call                       (optional escape-hatch)
 * RawCrafting  — craftRawTransaction        (not all chains accept externally-built txs)
 * Enrollment   — register                   (optional indexer backend)
 * Sequence     — getNextSequence            (some chains have no sequence/nonce concept)
 * Validation   — validateIntent,            (some chains cannot fully validate intents
 *                validateAddress             or addresses without a network round-trip)
 * AccountInfo  — getAccountInfo            (chain-specific account metadata; absent means
 *                                            "nothing to report", not "unsupported")
 */
export const optionalApiKeys = [
  'getBlock',
  'getBlockInfo',
  'getStakes',
  'getRewards',
  'getValidators',
  'call',
  'craftRawTransaction',
  'register',
  'getNextSequence',
  'validateIntent',
  'validateAddress',
  'getAccountInfo',
] as const

/**
 * A method name that a {@link CoinModuleImpl} author may omit.
 *
 * Derived from {@link optionalApiKeys} so the type and the runtime list used by
 * `withDefaults` cannot drift apart.
 */
export type OptionalApiKey = (typeof optionalApiKeys)[number]

/**
 * Methods every {@link CoinModuleImpl} author must implement: the minimum a chain has to
 * expose for the module to be usable at all. Complement of {@link optionalApiKeys}.
 */
export const requiredApiKeys = [
  'lastBlock',
  'getBalance',
  'listOperations',
  'craftTransaction',
  'estimateFees',
  'combine',
  'broadcast',
  'craftTransactionData',
] as const

/** A method name a {@link CoinModuleImpl} author must implement. */
export type RequiredApiKey = (typeof requiredApiKeys)[number]

/**
 * Every method the {@link CoinModuleApi} contract declares.
 *
 * Wrappers iterate this list to instrument an API without reflecting over the object at
 * runtime, so what they touch is fixed and readable rather than "whatever is a function".
 * `listFeeOptions` is neither required nor omittable — the contract itself declares it
 * optional and `withDefaults` does not backfill it — hence its place here and nowhere else.
 */
export const apiMethodKeys = [...requiredApiKeys, ...optionalApiKeys, 'listFeeOptions'] as const

/** A method name declared by the {@link CoinModuleApi} contract. */
export type ApiMethodKey = (typeof apiMethodKeys)[number]

/**
 * Compile-time guard: {@link apiMethodKeys} must name every method of the contract.
 *
 * Add a method to {@link CoinModuleApi} without listing it and `Unlisted` stops being
 * `never`, which this alias rejects — so a wrapper can never silently skip a new method.
 */
type AssertNever<T extends never> = T
export type ApiMethodKeysAreExhaustive = AssertNever<
  Exclude<keyof CoinModuleApi<CurrencyConfig>, ApiMethodKey>
>

/**
 * Authoring type for a coin-module implementation.
 *
 * Declare your module's `createApi` return type as `CoinModuleImpl<…>` instead of
 * `CoinModuleApi<…>`. Any method in the optional set (see source) may be omitted;
 * the framework's `withDefaults` wrapper will supply the "not supported" stub before
 * handing the object to consumers.
 *
 * The consumer/full contract ({@link CoinModuleApi}) is structurally unchanged —
 * it remains the required type at every call site.
 *
 * Generic parameters are identical to {@link CoinModuleApi}:
 *   - `ConfigType` — the coin-specific config shape
 *   - `MemoType`   — memo variant (defaults to {@link MemoNotSupported})
 *   - `TxDataType` — transaction data variant (defaults to {@link TxDataNotSupported})
 *
 * @see CoinModuleApi — the full consumer/runtime contract (unchanged)
 */
export type CoinModuleImpl<
  ConfigType extends CurrencyConfig,
  MemoType extends Memo = MemoNotSupported,
  TxDataType extends TxData = TxDataNotSupported,
> = Omit<CoinModuleApi<ConfigType, MemoType, TxDataType>, OptionalApiKey> &
  Partial<Pick<CoinModuleApi<ConfigType, MemoType, TxDataType>, OptionalApiKey>>