Skip to main content

Types

The 15 meta-tool definitions, what every Session method takes and returns, and where each wire type lives.

4 min read
View MarkdownEdit on GitHub

Types

@codespar/sdk re-exports everything in @codespar/types (export * from "@codespar/types"), so every wire type below imports from either package. The SDK adds its own configuration and loop types on top.

import type { ChargeArgs, ChargeResult, SessionConfig, LoopConfig } from "@codespar/sdk";

Where each type lives

AreaTypesSource
Client and session configCodeSparConfig, SessionConfig, CallOptions, Toolpackages/core/src/types.ts
Complete LoopLoopConfig, LoopStep, LoopResultsame file
Session contractSession, SessionBase, ToolResult, SendResult, StreamEvent, ToolCallRecord, ServerConnection, ProxyRequest, ProxyResult, AuthConfig, AuthResult, CreateSessionRequest, MockObject, MockValuepackages/types/src/types.ts
Meta-tool wrappersChargeArgs/ChargeResult, PayArgs/PayResult, KycArgs/KycResult, ShipArgs/ShipResult, LedgerArgs/LedgerResult, LedgerReceiptResult, LedgerReceiptsResult, AgenticReceipt, IssueArgs/IssueResult, ShopArgs/ShopResult (and the ShopSearch*, ShopCheckout*, ShopStatus* members of those unions)same file
Status polling and streamsPaymentStatus, PaymentStatusResult, PaymentStatusEvent, PaymentStatusStreamOptions, VerificationStatus, VerificationStatusResult, VerificationStatusEvent, VerificationStatusStreamOptionssame file
Discovery and connectionsDiscoverOptions, DiscoverResult, DiscoverToolMatch, DiscoverPlanStep, ConnectionWizardOptions, ConnectionWizardResult, ConnectionStatusRow, ConnectionWizardInstructionssame file
Tool-result codesToolResultCode, ToolResultOutcome, PolicyDeniedOutput, ApprovalRequiredOutput, MocksExhaustedOutput, MocksEngineErrorOutput, ToolNotMockedOutput and the *ToolCall narrowingspackages/core/src/tool-result-codes.ts
Meta-tool definitionsSharedMetaToolDefinition, MetaToolInputSchema, MetaToolInputProperty, MetaToolConformanceContract, SharedMetaToolName, MetaToolHook, MetaToolDefinition, MetaToolResult, MetaToolExecutionContextpackages/types/src/meta-tool-definitions.ts
REST client (from 0.12.0)ApiClientConfig, ApiPaths, ApiPath, ApiMethod, ApiOperation, ApiRequestOptions, ApiRequestBody, ApiResponse, ApiSuccess, ApiComponentspackages/core/src/api/types.ts

The shapes on the method pages are copied from those files at the commit the surface snapshot names. When a field here and a field there disagree, the file wins; the pages are corrected, not the code.

Two unit conventions worth reading twice: ChargeArgs.amount is in major units (R$ 125.00 is 125) while PayArgs.amount, LedgerLeg.amount and every *_minor field are in minor units (R$ 1.25 is 125); and every timeout in this SDK is in milliseconds, where the Python package takes seconds.

Meta-tool definitions

The 15 tools the hosted server lists, from the same tools/list snapshot the meta-tool pages are checked against. @codespar/types publishes each one as a SharedMetaToolDefinition constant (re-exported by @codespar/sdk), and SHARED_META_TOOL_DEFINITIONS keys them by wire name. "Typed wrapper" is the Session method that calls the tool with a typed argument and result; the rest go through session.execute(name, input).

ToolDefinition constantRequired inputTyped wrapper
codespar_discoverDISCOVER_DEFINITIONuse_casesession.discover()
codespar_get_startedGET_STARTED_DEFINITIONnonesession.execute("codespar_get_started", input)
codespar_manage_connectionsMANAGE_CONNECTIONS_DEFINITIONnonesession.connectionWizard()
codespar_checkoutCHECKOUT_DEFINITIONitemssession.execute("codespar_checkout", input)
codespar_payPAY_DEFINITIONactionsession.execute("codespar_pay", input)
codespar_walletWALLET_DEFINITIONactionsession.execute("codespar_wallet", input)
codespar_shopSHOP_DEFINITIONactionsession.shop()
codespar_chargeCHARGE_DEFINITIONnonesession.charge()
codespar_invoiceINVOICE_DEFINITIONtypesession.execute("codespar_invoice", input)
codespar_shipSHIP_DEFINITIONactionsession.ship()
codespar_notifyNOTIFY_DEFINITIONchannel, tosession.execute("codespar_notify", input)
codespar_crypto_payCRYPTO_PAY_DEFINITIONamount, currency, directionsession.execute("codespar_crypto_pay", input)
codespar_kycKYC_DEFINITIONbuyer, check_typesession.execute("codespar_kyc", input)
codespar_ledgerLEDGER_DEFINITIONactionsession.ledger()
codespar_issueISSUE_DEFINITIONactionsession.issue()

What each method takes and returns

Read from session.ts on the core's main branch (0.12.0). CallOptions is the per-call { timeout, signal } bag every method takes as a trailing opts; in @codespar/sdk since 0.12.0 (npm: 0.12.0). The method pages document it once, on the client page, rather than in every table.

MethodParametersReturns
toolsnonePromise<Tool[]>
findToolsintent: stringPromise<Tool[]>
executetoolName: string, params: Record<string, unknown>, opts?: CallOptionsPromise<ToolResult>
proxyExecuterequest: ProxyRequest, opts?: CallOptionsPromise<ProxyResult>
sendmessage: string, opts?: CallOptionsPromise<SendResult>
sendStreammessage: string, opts?: CallOptionsAsyncIterable<StreamEvent>
discoveruseCase: string, options?: DiscoverOptions, opts?: CallOptionsPromise<DiscoverResult>
connectionWizardoptions: ConnectionWizardOptions, opts?: CallOptionsPromise<ConnectionWizardResult>
chargeargs: ChargeArgs, opts?: CallOptionsPromise<ChargeResult>
shipargs: ShipArgs, opts?: CallOptionsPromise<ShipResult>
ledgerargs: LedgerArgs, opts?: CallOptionsPromise<LedgerResult>
issueargs: IssueArgs, opts?: CallOptionsPromise<IssueResult>
shopargs: ShopArgs, opts?: CallOptionsPromise<ShopResult>
paymentStatustoolCallId: string, opts?: CallOptionsPromise<PaymentStatusResult>
verificationStatustoolCallId: string, opts?: CallOptionsPromise<VerificationStatusResult>
paymentStatusStreamtoolCallId: string, options?: PaymentStatusStreamOptionsPromise<PaymentStatusResult>
verificationStatusStreamtoolCallId: string, options?: VerificationStatusStreamOptionsPromise<VerificationStatusResult>
authorizeserverId: string, config: AuthConfig, opts?: CallOptionsPromise<AuthResult>
connectionsopts?: CallOptionsPromise<ServerConnection[]>
closeopts?: CallOptionsPromise<void>
Types | CodeSpar