Portal API (dte-sdk/portal)

import { createPortalClient, openPortalSession, queryFolioQuota } from 'dte-sdk/portal'

// What each rejection means and what to do about it, in Spanish, for the operator.
const PORTAL_REJECTIONS: Readonly<Record<PortalRejection, string>>
 
// The Spanish message of a rejection.
function portalRejectionMessage(rejection: PortalRejection): string

// Validates and completes the options into a frozen `PortalClient`.
function createPortalClient(options: PortalClientOptions): PortalClient
 
// Retry policy of the portal: 4 attempts at 2, 4 and 8 s, no jitter, repeating what
// `isRetryablePortalError` accepts.
const DEFAULT_PORTAL_RETRY_POLICY: RetryPolicy
 
// True for what is worth repeating at the portal: transport failures, timeouts, HTTP 502/503/504,
// and the TLS failures the SII produces intermittently with a client certificate (`EPROTO …
// rsa_pss`), which are not a sign of a bad certificate.
function isRetryablePortalError(error: unknown): boolean

// Mutex per key inside one process.
function createMemoryPortalLock(): PortalLock

// Opens a session explicitly, reusing a cached one that is still alive, as the company page of the
// client's environment (`ad_empresa1`) says. The other operations do not need this: they log in
// on demand.
function openPortalSession(
  portal: PortalClient,
  overrides?: CallOverrides,
): Promise<PortalSessionInfo>
 
// Closes the session to give its slot back, and always removes the cached session. A failed logout
// is only logged: the SII expires the session on its own anyway.
function closePortalSession(portal: PortalClient, overrides?: CallOverrides): Promise<void>

// Reads the resolution of a company. It is per environment: certification and production answer
// different dates and numbers for one RUT, and the wrong pair gets an envelope rejected with
// "Error en Carátula".
function fetchCompanyResolution(
  portal: PortalClient,
  input?: { readonly companyRut?: string; readonly environment?: Environment; },
  overrides?: CallOverrides,
): Promise<CompanyResolution>
 
// Reads taxpayer data: name, address split in its parts, activities and branches.
function fetchTaxpayerData(
  portal: PortalClient,
  input?: { readonly companyRut?: string; },
  overrides?: CallOverrides,
): Promise<TaxpayerData>
 
// Reads the resolution and the taxpayer data in sequence and combines them. In parallel, one reply
// overwrites the balancer cookie the other needs and `ad_empresa2` answers empty.
function fetchIssuerProfile(
  portal: PortalClient,
  input?: { readonly companyRut?: string; readonly environment?: Environment; },
  overrides?: CallOverrides,
): Promise<IssuerProfile>

// Reads the state of each test set and book, on the certification host. It only reads: declaring
// progress is `declareProgress`.
function queryCertificationSets(
  portal: PortalClient,
  input?: { readonly companyRut?: string; },
  overrides?: CallOverrides,
): Promise<CertificationSets>

// Lists the document types the portal offers for stamping with this company. An error page is not
// "no types": a page with no selector and no stated rejection throws.
function listStampableTypes(
  portal: PortalClient,
  input?: { readonly companyRut?: string; },
  overrides?: CallOverrides,
): Promise<readonly StampableType[]>
 
// Reads how many folios the SII authorizes for a type, stopping at the form that shows it: nothing
// is stamped and the quota does not move. `MAX_AUTOR` and `FOLIOS_DISP` appear only while the SII
// rations the type. The form is the one whose selector has the type chosen: the company's page, with
// none chosen, is reloaded with it, and a last page that is not that form throws
// `SII_PORTAL_SESSION_EXPIRED` or `SII_PORTAL_UNEXPECTED_PAGE` instead of reading as an unrationed type.
function queryFolioQuota(
  portal: PortalClient,
  input: { readonly type: DocumentType; readonly companyRut?: string; },
  overrides?: CallOverrides,
): Promise<FolioQuota>
 
// Requests a range of folios and downloads its CAF through the five portal steps. A rejection can
// arrive at any step. With the effective maximum exceeded and no `minQuantity`, it asks once more
// for one folio. When the SII answers the request with the request form again, nothing is sent a
// second time: it throws `SII_PORTAL_REJECTED` with `stampingUncertain`, since the folios may have
// been granted, and `listReobtainableRanges` says whether they were.
function requestCaf(
  portal: PortalClient,
  input: CafRequestInput,
  overrides?: CallOverrides,
): Promise<ObtainedCaf>

// Lists the unused ranges of a document type, following the pages of the listing. It changes
// nothing.
function listFolioRanges(
  portal: PortalClient,
  input: { readonly type: DocumentType; readonly companyRut?: string; },
  overrides?: CallOverrides,
): Promise<FolioRanges>
 
// Annuls unused folios: up to four passes over the listing, by range and folio by folio when the
// part of the range was annulled or received before, stopping a pass after two real refusals in a
// row. A single folio keeps the SII's answer. Once the SII has answered for some folios, a
// `DteError` that ends the walk (an expired session, a block, the caller's abort, a later listing
// refused or not understood) comes back in `failure`, with what was done until then; a range that
// never got through (`transport`) is no answer, and before any answer the error is thrown. A range
// answered folio by folio comes back in as few pieces as its answers allow, and a walk cut short at
// one folio keeps the folios answered before it.
function annulFolios(
  portal: PortalClient,
  input: AnnulFoliosInput,
  overrides?: CallOverrides,
): Promise<AnnulmentResult>

// Lists the authorized ranges the SII lets download again. Annulled ranges appear there unmarked,
// so learning which are costs one request per range. The procedure is entered like the others, with
// a login on demand and the representation screen. Only a listing gives a list, empty when it has
// no ranges: a page that states a refusal throws `SII_PORTAL_REJECTED`, a login page
// `SII_PORTAL_SESSION_EXPIRED` and any other page `SII_PORTAL_UNEXPECTED_PAGE`.
function listReobtainableRanges(
  portal: PortalClient,
  input: { readonly type: DocumentType; readonly companyRut?: string; },
  overrides?: CallOverrides,
): Promise<readonly ReobtainableRange[]>
 
// Downloads the CAF of an already authorized range. It costs no quota. The procedure is entered
// first, as `listReobtainableRanges` enters it, with a login on demand, so a cached session that
// expired since the listing logs in again instead of posting the range with it. A page that states
// a refusal at the entry throws `SII_PORTAL_REJECTED` and any other page that is not the procedure
// `SII_PORTAL_UNEXPECTED_PAGE`, before anything is posted; a login page at any step throws
// `SII_PORTAL_SESSION_EXPIRED`, never the refusal of a step.
function reobtainCaf(
  portal: PortalClient,
  input: { readonly type: DocumentType; readonly range: ReobtainableRange; },
  overrides?: CallOverrides,
): Promise<ObtainedCaf>

// Requests one CAF that covers the whole quantity; below it nothing is stamped. With `allowAnnul`,
// once the SII has answered the annulment, a `DteError` that cuts it short, or one of the request
// asked once more after it, ends the flow with `rejection: null`, the first request's quota, the
// failure in `failure` and what was annulled in `knownAnnulled`; a cut-short annulment is not
// followed by another request. Before the annulment's first answer it throws.
function requestCafExact(
  portal: PortalClient,
  input: RequestCafExactInput,
  overrides?: CallOverrides,
): Promise<RequestCafExactResult>
 
// Covers a quantity across several CAFs, for when `FOLIOS_DISP` is 0 and `MAX_AUTOR` is small: the
// SII rations by history, there is nothing to annul or download again, and waiting does not move
// it. A refusal comes back with its own kind and `portalMessage`, on the first trip or a later one;
// after a grant, only one folio over the maximum (`quotaExceeded`) reads as `quotaCapReached`. Once
// a CAF is in hand, a later trip that fails with a `DteError` other than
// a refusal (a transport failure, a timeout, an expired session, a block, `CAF_INVALID`, the
// caller's abort) ends the flow with the CAFs obtained, the last quota seen and the failure in
// `failure`; with no CAF in hand it throws. `quantity` must be a whole number of at least 1, or it
// throws `INVALID_OPTION` before anything goes out.
function requestCafInBatches(
  portal: PortalClient,
  input: RequestCafInBatchesInput,
  overrides?: CallOverrides,
): Promise<FolioFlowResult>
 
// Covers a quantity from authorized ranges without spending quota, oldest folio first. It is what
// lifts a stamping block, since the SII asks for folios to be issued. The listing logs in on demand,
// and whatever fails while listing (a refusal, an expired session, a page that is not the listing)
// reads as no ranges, with the failure in `reason`: it does not throw. A refused download is logged
// and the walk moves on. Once a CAF is in hand, a download that fails with any other `DteError` (a
// transport failure, a timeout, an expired session, a block, the caller's abort) ends the walk with
// the CAFs downloaded, the failure's message in `reason` and the failure in `failure`; with no CAF
// in hand it throws. A login page in answer to the range or to the file is an expired session, not
// a refused download.
function reobtainFolios(
  portal: PortalClient,
  input: ReobtainFoliosInput,
  overrides?: CallOverrides,
): Promise<ReobtainResult>

// Changes the type of purchase of a document. In production this changes the real register.
function changePurchaseType(
  portal: PortalClient,
  input: ChangePurchaseTypeInput,
  overrides?: CallOverrides,
): Promise<void>
 
// One purchase as the register holds it, including its current type of purchase.
function fetchPurchaseDocument(
  portal: PortalClient,
  key: PurchaseDocumentKey,
  overrides?: CallOverrides,
): Promise<PurchaseDocument | null>
 
// The official totals of a period by document type and accounting status, including what the SII
// aggregates, such as receipts. Response codes are not looked at, so a month the SII refuses to
// show reads as an empty one.
function fetchRegisterSummary(
  portal: PortalClient,
  input: RegisterSummaryInput,
  overrides?: CallOverrides,
): Promise<RegisterSummary>
 
// Every document of a period, with no XML: the summary per type, then one detail call per row, at
// the same time. This is not the official register. Response codes are not looked at, so a month
// the SII refuses to show reads as an empty one.
function listPeriodDocuments(
  portal: PortalClient,
  input: ListPeriodDocumentsInput,
  overrides?: CallOverrides,
): Promise<PeriodDocuments>
 
// The types of purchase the SII lets a document have.
function listPurchaseTypes(
  portal: PortalClient,
  overrides?: CallOverrides,
): Promise<readonly PurchaseType[]>
 
// Moves the VAT of a document from recoverable to common use. In production this changes the real
// register.
function moveVatToCommonUse(
  portal: PortalClient,
  input: MoveVatInput,
  overrides?: CallOverrides,
): Promise<void>
 
// Moves the VAT of a document from common use back to recoverable: the inverse of
// `moveVatToCommonUse`, with the same rules. Moving it all back leaves `commonUseVat` at 0 and
// `recoverableVat` with the total.
function moveVatToRecoverable(
  portal: PortalClient,
  input: MoveVatInput,
  overrides?: CallOverrides,
): Promise<void>

import { REGISTER_ACCOUNTING_STATUSES, REGISTER_DOCUMENT_CODES, registerDocumentCode } from 'dte-sdk/portal'
 
registerDocumentCode(61)?.sign // -1: a credit note subtracts from the totals
registerDocumentCode(52)?.inRegister // false: dispatch guides never reach the register
registerDocumentCode(71) // undefined: not one of the 49 codes
REGISTER_DOCUMENT_CODES.length // 49
REGISTER_ACCOUNTING_STATUSES.sale // ['registered']

// The 49 document codes of the purchase and sales register, sorted by code.
const REGISTER_DOCUMENT_CODES: readonly RegisterDocumentCode[]
 
// What the register does with a document code, or `undefined` when the code is not one of the 49.
function registerDocumentCode(code: number): RegisterDocumentCode | undefined
 
// The accounting statuses each side of the register can hold: all four for purchases, only
// `registered` for sales, since no SII source describes other states of a sale.
const REGISTER_ACCOUNTING_STATUSES: Readonly<Record<RegisterOperation, readonly AccountingStatus[]>>

// Downloads the XML of the issued or received documents of a date range from the MIPYME backup,
// splitting the range until each piece fits the 20 documents the SII allows per download.
function downloadMipymeBackup(
  portal: PortalClient,
  input: MipymeBackupInput,
  overrides?: CallOverrides,
): Promise<MipymeBackup>

import { listAccreditationDocuments, unstable_fetchActivityVerification } from 'dte-sdk/portal'
 
const { requests, messages } = await unstable_fetchActivityVerification(portal)
requests.length // 0 when the company never asked for the verification
requests[0]?.status // 'PAC', described as 'PENDIENTE DE ACREDITACIÓN'
requests[0]?.preliminaryResult // 'CONDICIONADA'
requests[0]?.finalResult // null while there is none
requests[0]?.requestedOn // 'YYYY-MM-DD'
messages.filter((message) => message.blocking) // the messages the SII's own page stops at
 
const documents = await listAccreditationDocuments(portal)
documents[0] // { category: 'general', code: 1, description: '…' }

// Unstable: its shape may change in any release, a patch included. The company's activity
// verification, the SII's "Consulta estado de verificación y acreditación". It sends the company's
// RUT, not the session's, and a request of another RUT throws instead of passing as the company's.
// It reads production whatever the client's environment. Officials, comments and the address
// never come out.
function unstable_fetchActivityVerification(
  portal: PortalClient,
  input?: ActivityVerificationInput,
  overrides?: CallOverrides,
): Promise<ActivityVerification>
 
// The kinds of document the SII takes to accredit an activity, as the SII orders them: a general
// list and a specific one, whose codes repeat. It reads production whatever the client's
// environment.
function listAccreditationDocuments(
  portal: PortalClient,
  overrides?: CallOverrides,
): Promise<readonly AccreditationDocument[]>

// First 12 hex characters of the SHA-256 of a CAF file, to tell apart two files for one range.
function cafFingerprint(xml: string): string
 
// A registry over a store. Calls run one after another inside this process, each reading the
// ledger fresh; several processes need a store or a registry of their own that takes care of it.
function createFolioRegistry(store: FolioLedgerStore, now?: () => Date): FolioRegistry
 
// A registry that lives in memory: for tests and short runs.
function createMemoryFolioRegistry(now?: () => Date): FolioRegistry

// Kinds of set the SII test-set text can hold, by their English name.
const TEST_SET_KINDS: {
  readonly basic: "basic"
  readonly exempt: "exempt"
  readonly guide: "guide"
  readonly purchase: "purchase"
  readonly export: "export"
  readonly settlement: "settlement"
  readonly salesBook: "salesBook"
  readonly purchaseBook: "purchaseBook"
  readonly exemptPurchaseBook: "exemptPurchaseBook"
  readonly guideBook: "guideBook"
  readonly other: "other"
}
 
// Names of the sets and books as the certification portal lists them (`pe_avance2`).
const TEST_SET_PORTAL_NAMES: Readonly<Partial<Record<TestSetKind, string>>>
 
// The reference document type every document of a test set carries on its first reference line.
const TEST_SET_REFERENCE_TYPE = 'SET'
 
// The counterparty written on every entry of the certification purchase books: the SII's own RUT
// and a placeholder name. The SII accepts it, it exists as a taxpayer and it is nobody's personal
// data.
const CERTIFICATION_COUNTERPARTY: { readonly rut: "60803000-K"; readonly name: "Razon Social" }

// Parses the text of the SII test set: sets, their cases with items and references, the supplier
// documents of the purchase-book sets and the proportionality factor.
function parseTestSetText(text: string): readonly TestSet[]

// The cases each set issues, with the folios every document type needs, from the parsed sets. For
// each kind the last set of the text wins.
function planCertificationSets(sets: readonly TestSet[]): CertificationPlan

// A folio source over one or several CAFs: one counter per CAF, the first CAF of the type with a
// folio left wins, a folio is never given twice, and the CAF returned is the one whose range holds
// the folio, so it stamps with its own key.
function createFolioAllocator(cafs: readonly Caf[], options?: FolioAllocatorOptions): FolioSource

// Issues every document of a set plan and signs its envelope.
function issueTestSet(plan: IssuableSetPlan, options: IssueSetOptions): Promise<IssuedSet>
 
// `SetDTE/@ID` of every certification envelope.
const TEST_SET_ENVELOPE_ID = 'DTE_SetDoc'

// Issues every case of the four set plans again with fresh folios, in the order basic, exempt,
// guide and purchase, and signs one envelope with all of them.
function issueSimulation(
  plan: CertificationPlan,
  options: IssueSetOptions,
): Promise<IssuedSimulation>

// The sales book of the certification: only the basic set's invoices and notes, dated the 15th of
// the period, with the customer as counterparty, every amount present (0 when absent) and the VAT
// rate on every line.
function createCertificationSalesBook(
  set: IssuedSet | SalesBookSource,
  input: CertificationSalesBookInput,
): SignedPurchaseSalesBook
 
// A purchase book of the certification from a purchase-book set: one line per supplier document
// with the SII's placeholder counterparty, the VAT at 19 % of the affected amount, common-use VAT,
// non-recoverable VAT for free deliveries, the withholding of a purchase invoice, the referenced
// folio of a note from its observation, and, for the exempt taxpayers' book, non-recoverable VAT
// on every affected line, the paper exempt invoice as type 32 and notes inheriting the amounts of
// the document they reference.
function createCertificationPurchaseBook(
  plan: PurchaseBookPlan,
  input: CertificationBookInput,
): SignedPurchaseSalesBook
 
// The guide book of the certification: only the guide set's guides, with their transfer reason and
// issue date; by position the second guide carries `Operacion` 1 and the third is voided
// (`Anulado` 2, total 0 and nothing else), unless `caseFlags` says otherwise; a sale carries the
// customer, the net, the VAT rate and the VAT; every guide its total.
function createCertificationGuideBook(
  set: IssuedSet | GuideBookSource,
  input: CertificationGuideBookInput,
): SignedGuideBook

// The sets in the order they are sent.
const SET_KEYS: readonly SetKey[] = ['basic', 'guide', 'exempt', 'purchase']
 
// The books in the order they are sent.
const BOOK_KEYS: readonly BookKey[] = ['purchaseBook', 'salesBook', 'guideBook', 'exemptPurchaseBook']
 
// The books every certification must get approved.
const MANDATORY_BOOK_KEYS: readonly BookKey[] = ['purchaseBook', 'salesBook', 'guideBook']
 
// The file name each book travels under in the upload, as the SII expects it.
const BOOK_FILE_NAMES: Readonly<Record<BookKey, string>> = {
  salesBook: 'LibroCV.xml',
  purchaseBook: 'LibroCV.xml',
  exemptPurchaseBook: 'LibroCVExentos.xml',
  guideBook: 'LibroGuia.xml',
}
 
// The artefact name of each book.
const BOOK_ARTEFACT_NAMES: Readonly<Record<BookKey, string>> = {
  salesBook: 'libro-ventas.xml',
  purchaseBook: 'libro-compras.xml',
  exemptPurchaseBook: 'libro-compras-exentos.xml',
  guideBook: 'libro-guias.xml',
}
 
// The artefact name of each set envelope.
const SET_ARTEFACT_NAMES: Readonly<Record<SetKey, string>>
 
// The optional sets ticked when downloading the test set: guides (03), exempt invoices (06), the
// sales (07), purchase (08) and guide (09) books, the purchase book for exempt taxpayers (15) and
// the purchase set (72).
const DEFAULT_OPTIONAL_SETS: readonly string[] = ['SET03', 'SET06', 'SET07', 'SET08', 'SET09', 'SET15', 'SET72']
 
// The stages of a certification, in order, as the runner keeps them.
const CERTIFICATION_STAGES: readonly [
  "testSets", "books", "simulation", "exchange", "printedSamples", "compliance", "done"
]
 
// The words the portal uses for a stage (`pe_avance6`, "paso <b>…</b>"), from the latest stage
// down. Any wording past the exchange lands in `printedSamples`: the compliance declaration tells
// whether the samples are approved.
const PORTAL_STAGE_WORDS: readonly { readonly stage: CertificationStage; readonly words: readonly string[] }[]
 
// The names of the progress events the steps emit.
const CERTIFICATION_STEPS: readonly [
  "SETS_DOWNLOADING", "SETS_LOADED", "SETS_REGENERATED", "CAF_REQUESTING", "CAF_OK", "SET_START",
  "SET_OK", "SET_ERROR", "SETS_DECLARING", "SETS_DECLARED", "POLLING", "SETS_APPROVED",
  "SETS_REJECTED", "BOOKS_START", "BOOK_SKIPPED", "BOOK_SENDING", "BOOK_OK", "BOOK_ERROR",
  "BOOK_PERIOD_RETRY", "BOOKS_DECLARING", "BOOKS_DONE", "ADVANCE_WAITING", "ADVANCE_DONE",
  "SIM_START", "SIM_SENDING", "SIM_OK", "SIM_DECLARING", "SIM_DONE", "INTERCAMBIO_START",
  "INTERCAMBIO_DESCARGADO", "INTERCAMBIO_DONE", "MUESTRAS_UPLOADING", "MUESTRAS_DONE", "CERT_DONE",
  "CERT_ERROR"
]

// Downloads the test set from `pe_generar`. Without a session in the cache the progress page is
// read first, which logs in and lets the SII refresh the application; whatever that read answers,
// the download goes on.
function downloadTestSet(
  portal: PortalClient,
  input?: DownloadTestSetInput,
  overrides?: CallOverrides,
): Promise<DownloadedTestSet>
 
// Declares the track id and date of envelopes on `pe_avance2`, posted to `pe_avance3`. The form is
// read for its hidden fields and for the index of each row's field, found by the row's label (the
// indexes move as sets are approved).
function declareProgress(
  portal: PortalClient,
  input: DeclareProgressInput,
  overrides?: CallOverrides,
): Promise<DeclarationResult>
 
// Reads the progress page: the entry sequence, `pe_avance5`, then `pe_avance6` with the company.
// No page on the way is searched for a refusal, and a page that names no stage and no state is
// still an answer.
function readProgress(
  portal: PortalClient,
  input?: { readonly companyRut?: string; },
  overrides?: CallOverrides,
): Promise<ProgressReport>
 
// Asks the portal to move the application to its next stage: `pe_avance4` with `TOTREG` and `PASO`
// as `pe_avance2` holds them (`PASO` changes with the stage; a fixed value makes the SII answer
// "ya se encuentra en el paso"), with `pe_avance2` as referer.
function advanceStage(
  portal: PortalClient,
  input?: { readonly companyRut?: string; },
  overrides?: CallOverrides,
): Promise<AdvanceResult>
 
// Lists the books the SII holds for a year (`QEstLibro`, after `DTEauth?7` binds the session to
// that CGI). Every period listed is occupied for a new total submission.
function listBookHistory(
  portal: PortalClient,
  input: { readonly year: number; readonly companyRut?: string; },
  overrides?: CallOverrides,
): Promise<BookHistory>
 
// The declaration of compliance: `pe_avance7`, `pe_avance8` with the company, once more with every
// input of the page when the portal asks to continue (`OK_MSG`), then the `pe_avance9` form with
// every input of the page, `Salir` apart, every `OPCn` at `S` and `CONFIRMAR`, both posts with
// `pe_avance8` as referer.
function declareCompliance(
  portal: PortalClient,
  input?: { readonly companyRut?: string; },
  overrides?: CallOverrides,
): Promise<ComplianceResult>

// A fresh state for a company.
function createCertificationState(companyRut: string, now?: Date): CertificationState
 
// A store in memory: for tests and short runs.
function createMemoryCertificationStore(): CertificationStore
 
// Throws unless the name is a relative path of safe segments: no empty segment, no `.`, no `..`,
// no absolute path, nothing outside `[A-Za-z0-9._-]`.
function assertArtefactName(name: string): void
 
// A store in a directory: `state.json` written atomically (temp file and rename), the artefacts as
// files, a `/` in a name as a sub-directory.
function createDirectoryCertificationStore(
  options: DirectoryCertificationStoreOptions,
): CertificationStore

// What the run fills in for an issuer that leaves it out: the line of business, the activity code,
// the commune and the city. The RUT, the name and the address have no default.
const DEFAULT_CERTIFICATION_ISSUER: Readonly<{ businessActivity: "ACTIVIDADES DE PROGRAMACION INFORMATICA"; activityCode: 620200...
 
// The test receiver the run uses when none is given.
const DEFAULT_CERTIFICATION_RECEIVER: ReceiverInput

// Downloads the test set, parses it, plans the sets and keeps the text and the plan as artefacts.
// Downloading generates the set anew at the SII, so a run that already had a plan starts over:
// everything sent is void.
function obtainTestSet(
  deps: CertificationDependencies,
  state: CertificationState,
  options?: { readonly optionalSets?: readonly string[]; },
): Promise<StepResult<"loaded" | "regenerated">>
 
// Sends one test set: issues it with the folios of the state's CAFs through the registry, keeps
// the envelope and every document as artefacts, uploads it, marks the folios sent whatever
// happened, and records the track id and the Chile date of the send.
function sendTestSet(
  deps: CertificationDependencies,
  state: CertificationState,
  options: { readonly kind: SetKey; },
): Promise<StepResult<"sent">>
 
// Declares the sets sent so far with today's date, with the declaration loop; the outcome and any
// diagnosis go to the state.
function declareTestSets(
  deps: CertificationDependencies,
  state: CertificationState,
): Promise<DeclarationStepResult>
 
// Waits for the sent sets to be approved: 5 attempts 10 s apart, sleeping first, reading the
// progress page. A read that fails only uses up its attempt.
function waitForTestSetsApproval(
  deps: CertificationDependencies,
  state: CertificationState,
): Promise<StepResult<"approved" | "rejected" | "timedOut">>
 
// Asks the portal for the next stage after the books: the progress page is read, up to 30 times 10
// s apart while it cannot be read; on the first page that reads the advance is asked for at once,
// whatever the page says of the books (the portal decides); then the page is read again for the
// stage, and the state's stage moves to the portal's when that is later.
function advanceToNextStage(
  deps: CertificationDependencies,
  state: CertificationState,
): Promise<StepResult<"advanced" | "unchanged" | "failed" | "timedOut">>
 
// Sends the simulation: fresh CAFs for one folio per case (never the sets' CAFs), every case of
// the four sets issued again in one envelope, the envelope and the documents kept as artefacts,
// the upload, the folios marked sent whatever happened, and the track id with the Chile date of
// the send.
function sendSimulation(
  deps: CertificationDependencies,
  state: CertificationState,
): Promise<StepResult<"sent">>
 
// Declares the simulation, unless the progress page names the exchange as the step the application
// is at: a later step is declared like any other, and so is a page that cannot be read.
function declareSimulation(
  deps: CertificationDependencies,
  state: CertificationState,
): Promise<DeclarationStepResult<DeclarationOutcome | "skipped">>
 
// Waits for the simulation: 30 polls 10 s apart of the progress page, polling first. A read that
// fails only uses up its attempt.
function waitForSimulationApproval(
  deps: CertificationDependencies,
  state: CertificationState,
): Promise<StepResult<"done" | "confirmed" | "rejected" | "timedOut">>
 
// The end of the certification: one more request to advance the stage, then the declaration of
// compliance.
function declareComplianceFinal(
  deps: CertificationDependencies,
  state: CertificationState,
): Promise<StepResult<"declared" | "blocked">>

// Makes sure the run holds the folios each type needs. The CAFs in hand first: an expired one is
// skipped, folios of this run the SII never received are given back, and folios the SII already
// received are marked used so they are skipped. Every CAF obtained is saved in the state at once.
// Still short it throws `FOLIO_OUT_OF_RANGE` or, when the batches stopped on a failure and not on
// the SII's answer, that failure's code. A re-obtaining or an annulment cut short by a failure ends
// the step with that failure's code too, once what it brought and was kept, or what it annulled, is
// in the state. Only a rationing refusal leads to annulling: a later batch refused for the company,
// the option or the person keeps its kind, and a block on the person is first lifted by re-obtaining.
function prepareFolios(
  deps: CertificationDependencies,
  state: CertificationState,
  options?: PrepareFoliosOptions,
): Promise<PrepareFoliosResult>
 
// The folios each type needs for the sets not yet sent: the sum of each set plan's `folios`, never
// more, because unused authorized folios make the SII ration the next request.
function setFolioNeeds(
  plan: CertificationPlan,
  sent: readonly string[],
): Readonly<Record<number, number>>
 
// The folios the simulation needs: one per case, by type.
function simulationFolioNeeds(plan: CertificationPlan): Readonly<Record<number, number>>

// The books phase.
function runBooks(
  deps: CertificationDependencies,
  state: CertificationState,
): Promise<StepResult<BooksOutcome>>
 
// The month before a `YYYY-MM` period.
function previousPeriod(period: string): string
 
// The first period at or below `period` the SII does not hold, stepping down month by month, at
// most 400 times.
function nextFreePeriod(period: string, occupied: ReadonlySet<string>): string

// The exchange portal (`pfeInternet`): the certification's exchange set is downloaded there and
// its answers uploaded.
const EXCHANGE_PORTAL: GwtPortal
 
// The printed samples portal (`pdfdteInternet`), the SII's automatic validator of the printed
// documents.
const SAMPLES_PORTAL: GwtPortal
 
// The file names of the exchange answers, as the portal's uploads name them: the reception
// response, the receipts and the commercial approval.
const EXCHANGE_ANSWER_FILES: Readonly<Record<ExchangeAnswerKey, string>> = {
  reception: 'respuesta-recepcion-envio.xml',
  receipts: 'envio-recibos.xml',
  approval: 'respuesta-aprobacion-comercial.xml',
}
 
// The exchange answers in upload order.
const EXCHANGE_ANSWER_KEYS: readonly ExchangeAnswerKey[] = ['reception', 'receipts', 'approval']

// The request body of a call: `7|0|N|` + the string table + the body, every item followed by `|`.
function gwtBody(call: GwtCall): string
 
// Reads an answer: `//OK`, the string table, the message, the Long tokens.
function gwtAnswer(body: string): GwtAnswer
 
// A number in the GWT base-64 alphabet, most significant digit first (`264872` is `BAqo`).
function encodeGwtLong(value: number): string
 
// The number a GWT base-64 token holds, or null when a character is not in the alphabet.
function decodeGwtLong(token: string): number | null
 
// The hashes of a GWT portal: the caller's pair when given; else the module's `nocache.js` is read
// (the 32-hex strings delimited by `=`, `'` or `,`): the known pair stands when its permutation is
// listed, else the first one listed is the permutation and its `cache.html` gives the policy, the
// first quoted 32-hex string that differs from it; any failure, empty page or missing candidate
// keeps the known pair.
function discoverGwtHashes(context: PortalContext, input: GwtDiscoveryInput): Promise<GwtHashes>

// Downloads the exchange set from the exchange portal: the warm-up, then `downloadFile` with the
// company in the query and an empty multipart body. The download does not change the application.
function downloadExchangeSet(
  portal: PortalClient,
  input?: ExchangeCompanyInput,
  overrides?: CallOverrides,
): Promise<ExchangeSetDownload>
 
// Validates the user on the exchange portal: the warm-up, then `validarUsuario` with the company
// and the certificate holder over the known hashes. The answer says whether the company stands in
// the exchange stage; `//OK` is not required.
function validateExchangeUser(
  portal: PortalClient,
  input?: ExchangeGwtInput,
  overrides?: CallOverrides,
): Promise<ExchangeUserValidation>
 
// Uploads the three exchange answers, in the portal's order: the reception response to
// `uploadFile1`, the receipts to `uploadFile2`, the commercial approval to `uploadFile3`, each a
// single `uploadFormElement` part.
function uploadExchangeAnswers(
  portal: PortalClient,
  input: UploadExchangeAnswersInput,
  overrides?: CallOverrides,
): Promise<ExchangeUploadResult>
 
// Confirms the exchange on the portal: `validarSetContriPostSeguimiento` with the company (its
// answer is kept, not judged), then `updatePostulacionSeguimiento` for the follow-up ids 40, 41
// and 43, one per uploaded answer, each of which must answer `//OK`.
function confirmExchange(
  portal: PortalClient,
  input?: ExchangeGwtInput,
  overrides?: CallOverrides,
): Promise<ExchangeConfirmation>
 
// Runs `run` in one stage of the exchange portal: the session made sure of, one warm-up, and every
// call that is given the stage sent once over it. The upload, the user validation and the
// confirmation share one stage.
function withExchangeStage<T>(
  portal: PortalClient,
  operation: string,
  overrides: CallOverrides | undefined,
  run: (stage: GwtStage) => Promise<T>,
  sessionChecked?: boolean,
): Promise<T>

// Reads the company's printed samples review: `leeImpreso` with the company RUT. The portal
// answers HTTP 200 with a state, or with a sentence when the application is not in the printed
// samples stage (before it, and after it too).
function readSamplesReview(
  portal: PortalClient,
  input?: ReadSamplesReviewInput,
  overrides?: CallOverrides,
): Promise<SamplesReview>
 
// Creates a printed samples review: `creaLista` with the company as sender and provider. The
// portal only creates one when the current review is `RECHAZADO` or `APROBADO`, or there is none;
// a review in `INGRESO` is resumed instead.
function createSamplesReview(
  portal: PortalClient,
  input?: SamplesCompanyInput,
  overrides?: CallOverrides,
): Promise<SamplesReviewCreated>
 
// Uploads one PDF to a review: `POST upload` with the parts `Filedata` (the file), `id` (the
// review id in decimal) and `ambiente` (`false`), the referer the permutation's `cache.html`. HTTP
// 200 is success.
function uploadSample(
  portal: PortalClient,
  input: UploadSampleInput,
  overrides?: CallOverrides,
): Promise<SampleUploaded>
 
// Submits a review to the SII: `solicitaRevisionSII` with the review token. The answer is
// `//OK[0,[],0,7]` whether the SII accepts or rejects the samples: the state is read again
// afterwards.
function submitSamplesReview(
  portal: PortalClient,
  input: SamplesReviewInput,
  overrides?: CallOverrides,
): Promise<{ readonly body: string; }>
 
// Reads how the SII filed each PDF of a rejected review: `muestraMail` with the review token. A
// failure is logged and gives an empty detail: the rejection stands without it.
function readSamplesDetail(
  portal: PortalClient,
  input: SamplesReviewInput,
  overrides?: CallOverrides,
): Promise<SamplesDetail>
 
// Runs `run` in one stage of the samples portal: the session made sure of, one warm-up, the hashes
// looked up once, and every call that is given the stage sent once over it.
function withSamplesStage<T>(
  portal: PortalClient,
  operation: string,
  overrides: CallOverrides | undefined,
  run: (stage: GwtStage) => Promise<T>,
): Promise<T>

// Builds and signs the three answers to an exchange set, as the certification expects them: the
// reception response (the envelope received, every document received when its receiver is the
// company, else "error en RUT receptor"), the receipts of Ley 19.983 (one per document, signed by
// the certificate holder) and the commercial approval (accepted when the receiver is the company,
// else rejected with `CodRchDsc` -1).
function createExchangeAnswers(setXml: string, input: CreateExchangeAnswersInput): ExchangeAnswers
 
// Reads the exchange set loosely: the XML is not checked for well-formedness and its tags are read
// by their full name, so a prefixed envelope is no envelope; the root is `EnvioDTE`, `EnvioDTEB`,
// `EnvioDTETraslado` or `EnvioBOLETA`; the set id (the `ID` attribute, else an `ID` child, else
// `SetDTE`), the cover's RUTs and, per document, its type (`TipoDTE` or `TpoDoc`), folio, issue
// date, issuer and receiver (the cover's when the document names none) and total.
function parseExchangeSet(setXml: string): ExchangeSet

// The exchange stage: the set (given, kept from an earlier run, or downloaded), the three answers
// generated and kept as artefacts, the user validated on the portal, the answers uploaded and the
// exchange confirmed, which moves the application to the printed samples.
function runExchange(
  deps: CertificationDependencies,
  state: CertificationState,
  input?: RunExchangeInput,
): Promise<StepResult<ExchangeOutcome>>
 
// The artefact that holds the exchange set; the caller fills it by hand when the download fails.
const EXCHANGE_SET_ARTEFACT: "intercambio/set-intercambio.xml"
 
// The printed samples stage: the review read (a block or a review already sent end here; none yet
// is created), resumed when it stands in `INGRESO` with a readable id or created otherwise, every
// PDF uploaded in order (each name saved as it goes), the review submitted, and its state read
// again (a failed reading is warned about and leaves the state unknown): `RECHAZADO` brings the
// detail and its summary.
function uploadPrintedSamples(
  deps: CertificationDependencies,
  state: CertificationState,
  input: UploadPrintedSamplesInput,
): Promise<StepResult<SamplesOutcome>>

// The HTML side of the certification, in stage order, resumed from the saved state: the test set
// (downloaded once), the folios, each set not yet sent, their declaration and approval; the books;
// the advance; the simulation sent, declared and confirmed; the exchange set answered, uploaded
// and confirmed; the printed samples uploaded and submitted when the `samples` option gives them
// (else it stops there); and then it declares compliance, only with `declareCompliance: true`,
// because that declaration cannot be undone.
function runCertification(
  dependencies: CertificationDependencies,
  options?: RunCertificationOptions,
): Promise<RunCertificationResult>

// The receipts portal (`certBolElectDteInternet`), where the certification of electronic receipts
// runs. Its hashes are not discovered: `moduleName` is what its interface suggests, not a recorded
// fact.
const RECEIPTS_PORTAL: GwtPortal
 
// Parses the receipts test set the receipts portal delivers, a plain text.
function parseReceiptsTestSet(text: string): readonly ReceiptsTestCase[]

// Issues the receipts test set: one receipt of type 39 per case, in order, each with the next
// folio of the source, the final consumer as receiver, the prices of the set taken as including
// VAT, the exemption of an exempt item, the unit of measure an observation names on its first
// item, and one reference with the code `SET` and the reason `CASO-<n>`; then signs the
// `EnvioBOLETA` that carries them, with the certificate holder as sender (the issuer when the
// certificate names none) and the SII as receiver.
function issueReceiptsSet(
  cases: readonly ReceiptsTestCase[],
  options: IssueReceiptsSetOptions,
): Promise<IssuedReceiptsSet>

// Sends the receipts set: uploads the envelope and reads the reply (`STATUS` 0 with a track id is
// sent; `STATUS` 7 with a track id is also taken as sent, and without one it is a duplicate that
// skips to the report with no track id; `STATUS` 99 and any other reply is a failure and throws),
// waits 20 s and reads the status of a sent envelope once (a rejection ends here; a query that
// never got through is logged, and an answer without a state, or an unknown one, blocks nothing),
// then sends the folio consumption report built from the envelope, with the sequence number
// `sequence` plus the attempt, up to ten attempts: a `STATUS` 7 without a track id is a duplicate
// and three in a row mean today's report was already accepted; a `STATUS` 99 or another refusal
// ends it as `consumptionFailed`; an uploaded report is given 30 s and its status read once: a
// success or an intermediate state (a query error code or `0` too) accepts it, a query that never
// got through accepts it, and anything else (a rejection, no state, an unknown state) tries the
// next sequence number, unless its gloss speaks of authorisation or signing.
function sendReceiptsSet(
  sii: SiiClient,
  issued: { readonly envelope: SignedEnvelope; },
  options?: SendReceiptsSetOptions,
): Promise<ReceiptsSendResult>
 
// Builds the folio consumption report again from a receipts envelope already sent and uploads it
// once, with the sequence number given.
function resendReceiptsConsumption(
  sii: SiiClient,
  input: ResendReceiptsConsumptionInput,
): Promise<{ readonly sequence: number; readonly xml: string; readonly trackId: string; readonly duplicate: boolean; }>

// Downloads the receipts test set.
function downloadReceiptsTestSet(
  portal: PortalClient,
  input?: DownloadReceiptsTestSetInput,
  overrides?: CallOverrides,
): Promise<ReceiptsTestSetDownload>
 
// Declares the track id of the receipts envelope, so the SII validates the set
// (`ingresarTrackId`), exactly as it is given. Sent once.
function declareReceiptsTrackId(
  portal: PortalClient,
  input: ReceiptsPortalInput & { readonly trackId: string; },
  overrides?: CallOverrides,
): Promise<{ readonly body: string; }>
 
// Reads the state of the receipts application: whether the company is enrolled (it has valid
// representatives), whether the SII approved the set (`P90`, ready to declare) and whether the
// declaration was made (`P91`).
function readReceiptsStatus(
  portal: PortalClient,
  input?: ReceiptsPortalInput,
  overrides?: CallOverrides,
): Promise<ReceiptsStatus>
 
// Makes the declaration of compliance of the receipts application, which authorises the company to
// issue receipts in production (`autorizarEmpresaBolProd`). It cannot be undone.
function declareReceiptsCompliance(
  portal: PortalClient,
  input: DeclareReceiptsComplianceInput,
  overrides?: CallOverrides,
): Promise<ReceiptsComplianceResult>
 
// Reads whether the company may issue receipts. In production, a GET of the stamping entry page
// and a POST of its form with the company, and type 39 among the quoted option values of the
// answer (which must have a selector).
function verifyReceiptsAuthorization(
  input: VerifyReceiptsAuthorizationInput,
): Promise<ReceiptsAuthorization>