tungo-sdk 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c415a9a9702c830f7036d0f2331956c57bfcfb84e75e55069491d26433335903
+  data.tar.gz: 32dee197f111c665c358d3a4420282e997cff09c1591a204dfc59e9cb5b71526
+SHA512:
+  metadata.gz: e6ca9fc4de6f8069f52c786140699f17af038928276c8fd07f099b44e37a7ac2efa5268e9f572f4b61d1dab7093a9cd68bd66d6036383b3917fd67a54b39bfb7
+  data.tar.gz: d6be717d231df82023c2b2117b512806e18522db02424b2efa5522814ddbae60e0557fb3b4bd84c19f14a15f4733d1dcc698513093f1f64a91c170daffb4a687

data/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to the Tungo SDK for Ruby are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+<!-- Generated by tungo-sdkgen: edit changelogReleases in the generator, not this file. -->
+
+## [Unreleased]
+
+## [0.2.0] - 2026-11-12
+
+First production-ready release. It contains breaking changes compared with 0.1.0; 0.1.0 should not be used.
+
+### Changed
+
+- Requests and responses use typed models generated from the API contract.
+- Errors are classified by the `error.type` of the API error envelope, with the HTTP status as a fallback; the `hint` field, which the API never sent, is removed.
+- Retries happen only for requests that are safe to repeat (idempotent methods, or requests carrying an `Idempotency-Key`), with jittered exponential backoff that honours `retry-after-ms` and `Retry-After`.
+- Timeouts cover the whole request, are configurable per client and per request, and combine with caller-supplied cancellation.
+- Server-sent events are delivered incrementally; closing or abandoning a stream closes the connection.
+- List methods return typed pages and offer an auto-paging iterator.
+- Webhook verification enforces the timestamp tolerance against the system clock and reports every failure as a typed error.
+- Money helpers parse decimal strings exactly; tiyn amounts are 64-bit integers.
+- The default base URL is `https://api.tungo.kz`; it can be set with `TUNGO_BASE_URL`.
+
+## [0.1.0] - 2026-11-09
+
+Initial preview. Not suitable for production use.
+
+[Unreleased]: https://github.com/TungoAI/tungo-sdk-ruby/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/TungoAI/tungo-sdk-ruby/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/TungoAI/tungo-sdk-ruby/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tungo AI (https://tungo.kz)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,316 @@
+<!-- Generated by tungo-sdkgen. Do not edit: the file is rewritten on every generation. -->
+
+<div align="center">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/TungoAI/.github/main/assets/logo02.svg" />
+  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/TungoAI/.github/main/assets/logo03.svg" />
+  <img alt="Tungo AI" src="https://raw.githubusercontent.com/TungoAI/.github/main/assets/logo03.svg" width="240" />
+</picture>
+
+# Tungo SDK for Ruby
+
+**The official Ruby library for the Tungo Platform API**
+
+[![RubyGems](https://img.shields.io/gem/v/tungo-sdk)](https://rubygems.org/gems/tungo-sdk)
+[![CI](https://github.com/TungoAI/tungo-sdk-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/TungoAI/tungo-sdk-ruby/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/TungoAI/tungo-sdk-ruby/blob/main/LICENSE)
+
+**English** · [Русский](https://github.com/TungoAI/tungo-sdk-ruby/blob/main/README.ru.md) · [Қазақша](https://github.com/TungoAI/tungo-sdk-ruby/blob/main/README.kk.md)
+
+[tungo.kz](https://tungo.kz) · [Quick start](#quick-start) · [API reference](#api-reference) · [Changelog](https://github.com/TungoAI/tungo-sdk-ruby/blob/main/CHANGELOG.md) · [Issues](https://github.com/TungoAI/tungo-sdk-ruby/issues)
+
+</div>
+
+---
+
+The official Ruby library for the Tungo Platform API (`https://api.tungo.kz`): the AI accountant, 1C integration, bank statements, e-invoices, tax forms and automations of [Tungo AI](https://tungo.kz).
+
+It is generated from the API's OpenAPI contract, so its methods and models always match the contract it was built from.
+
+## Requirements
+
+Ruby 3.2 or newer; the test suite runs on Ruby 3.2, 3.3, 3.4, 4.0. HTTP goes through `Net::HTTP` from the standard library with persistent connections. The only runtime dependencies are `base64` and `bigdecimal`, default gems that newer Rubies load only when they are declared. RBS signatures for the whole public API ship in `sig/`.
+
+## Installation
+
+```sh
+bundle add tungo-sdk
+# or
+gem install tungo-sdk
+```
+
+Load it with `require "tungo"` (Bundler's automatic require works too; `require "tungo-sdk"` is an alias).
+
+## Quick start
+
+```ruby
+require "tungo"
+
+client = Tungo::Client.new(api_key: ENV.fetch("TUNGO_API_KEY"), company_id: "co_01h455vb4pex5vsknk084sn02q")
+
+result = client.ask("Покажи дебиторку за октябрь")
+puts result.answer
+puts "dialog #{result.dialog_id}"
+
+client.companies.list.data.each { |company| puts company.name }
+```
+
+## Authentication and configuration
+
+Create one client and share it: it is immutable and safe to use from several threads or tasks. Every option can be passed explicitly; five of them fall back to environment variables.
+
+| Option | Environment variable | Default |
+| --- | --- | --- |
+| API key | `TUNGO_API_KEY` | none |
+| Base URL | `TUNGO_BASE_URL` | `https://api.tungo.kz` |
+| Webhook secret | `TUNGO_WEBHOOK_SECRET` | none |
+| Default company | `TUNGO_COMPANY_ID` | none |
+| Default workspace | `TUNGO_WORKSPACE_ID` | none |
+| Timeout | | 60 s (600 s for non-streaming chat turns) |
+| Maximum retries | | 2 |
+| Default headers, HTTP client | | none, built-in |
+
+The API key is sent only to operations that require it; public endpoints and incoming hooks never receive it, and it never appears in error messages or debug output. Calling an authenticated operation without a key fails locally, before any request is made.
+
+Every method also accepts per-request options: timeout, maximum retries, extra headers, an idempotency key and cancellation.
+
+```ruby
+client = Tungo::Client.new(
+  api_key: ENV.fetch("TUNGO_API_KEY"),       # default: ENV["TUNGO_API_KEY"]
+  base_url: ENV.fetch("TUNGO_BASE_URL"),     # default: ENV["TUNGO_BASE_URL"], then the production API
+  webhook_secret: "whsec_c2VjcmV0",          # default: ENV["TUNGO_WEBHOOK_SECRET"]
+  company_id: "co_01h455vb4pex5vsknk084sn02q",
+  workspace_id: "ws_01h455vb4pex5vsknk084sn02q",
+  timeout: 60,
+  max_retries: 2,
+  default_headers: { "X-App" => "billing" }
+)
+
+# Per-request options
+dialog = client.chat.get(
+  "0b5f6a0e-6a1c-4d55-9a57-2f1d8b9c3e10",
+  request_options: { timeout: 10, max_retries: 0, extra_headers: { "X-Trace" => "abc" } }
+)
+puts dialog.api_response.request_id
+puts dialog.api_response.rate_limit&.remaining
+```
+
+Parameters are keyword arguments: path ids are positional, everything else is named. `nil` and "not given" are different: `nil` is sent as JSON `null` where the API accepts it, an argument you leave out is not sent at all. Company-scoped methods use the client's `company_id` unless you pass `company_id:` to the call (the same goes for `workspace_id`); the two defaults also fall back to `TUNGO_COMPANY_ID` and `TUNGO_WORKSPACE_ID`.
+
+Every result exposes the HTTP response it came from through `api_response` (status, headers, request id, rate-limit headers of that very response); operations without a response body return it directly. To cancel a call, interrupt its thread (`Thread#raise`, `Thread#kill`, `Timeout.timeout`): sockets and back-off sleeps are interruptible and the connection is closed.
+
+The API key must be printable ASCII without spaces or line breaks: a key read from a file with its trailing newline is refused with `Tungo::ConfigError` when the client is built (the key itself is never printed). `default_headers:` that carry credentials (`Authorization`, `X-Api-Key`, `Proxy-Authorization`, `Cookie`) are sent only to operations authenticated with the API key, never to `POST /hooks/{token}` or to public endpoints; a header given for one call through `request_options: { extra_headers: ... }` is always sent.
+
+`client.close` closes the pooled connections. `Tungo::Client.new(transport: Tungo::Transport::NetHTTP.new(proxy: "http://proxy:8080") { |http| http.ca_file = "ca.pem" })` customises the connections; any object with the same `execute` method can replace the transport.
+
+## Errors
+
+Every failure is a subtype of the SDK's base error. An HTTP error response becomes an API error chosen by the `error.type` field of the response body, falling back to the HTTP status when the body is not the API's error envelope:
+
+| `error.type` | Status |
+| --- | --- |
+| `invalid_request_error` | 400 |
+| `authentication_error` | 401 |
+| `payment_required_error` | 402 |
+| `permission_error` | 403 |
+| `not_found_error` | 404 |
+| `conflict_error` | 409 |
+| `gone_error` | 410 |
+| `limit_error` | 429 |
+| `api_error` | 500 |
+| `unavailable_error` | 503 |
+
+An API error carries the status, type, code, message, request id, field errors, the parsed retry-after delay, the response headers and the raw body. Problems that happen without a response have their own types: connection error, timeout, decode error (a successful response whose body is not valid), and configuration or validation error (raised before any request).
+
+```ruby
+begin
+  client.proposals.approve("P-000042")
+rescue Tungo::LimitError => e
+  warn "Limit reached, retry in #{e.retry_after} s"
+rescue Tungo::InvalidRequestError => e
+  e.fields.each { |field| warn "#{field.path}: #{field.message}" }
+rescue Tungo::APIError => e
+  warn "#{e.status} #{e.type} #{e.code}: #{e.api_message} (request #{e.request_id})"
+rescue Tungo::TimeoutError, Tungo::ConnectionError => e
+  warn "Network problem: #{e.message}"
+end
+```
+
+The class names are `Tungo::InvalidRequestError`, `AuthenticationError`, `PaymentRequiredError`, `PermissionError`, `NotFoundError`, `ConflictError`, `GoneError`, `LimitError`, `ServerError` (`api_error`) and `UnavailableError`, all subclasses of `Tungo::APIError`. Without a response the SDK raises `Tungo::ConnectionError`, `Tungo::TimeoutError`, `Tungo::DecodeError`, `Tungo::ConfigError` or `Tungo::ValidationError`; all of them inherit from `Tungo::Error`, and the original exception is kept in `cause`.
+
+`Tungo::DecodeError` means the API answered with a success status but the body could not be used: it is not JSON, it is empty, a declared property has the wrong JSON kind (a string where the contract says number, an object where it says array, and so on), a stream call was answered with something other than `text/event-stream`, or a chat stream ended before its `done` event. The check of kinds is deliberately light: only the properties of the top-level object, and `null`, missing properties, unknown properties and unknown enumeration values are always accepted. The error carries `api_response` and the raw `body`. The request itself was accepted by the server, so do not repeat a write because of it.
+
+`client.ask` raises the typed `Tungo::APIError` when the turn reports an error in its `errors` list; pass `raise_on_error: false` to get the result with the errors instead.
+
+## Retries and timeouts
+
+A request is retried up to 2 times (3 attempts) on connection errors, timeouts and the statuses 408, 429, 500, 502, 503 and 504, but only when repeating it is safe: `GET`, `HEAD`, `PUT` and `DELETE` requests, and `POST` or `PATCH` requests that carry an `Idempotency-Key`. For the operations whose contract declares that header the SDK generates a random key and reuses it for every attempt; you can pass your own.
+
+The delay between attempts is `min(0.5 s × 2^attempt, 8 s)` with random jitter. A positive `retry-after-ms` or `Retry-After` response header overrides it; if the server asks for more than 60 s the SDK does not wait and raises the error with the delay filled in.
+
+The timeout covers the whole request including reading the body. Streaming calls have no total timeout, only a connect timeout and an idle timeout of 120 s. Cancellation supplied by the caller is combined with the timeout.
+
+```ruby
+client = Tungo::Client.new(max_retries: 5, timeout: 20)
+
+client.companies.list(request_options: { max_retries: 0, timeout: 5 })
+client.proposals.approve("P-000042", request_options: { idempotency_key: "approve-P-000042" })
+```
+
+`chat_timeout:` (600 s) is the client-wide timeout of non-streaming chat turns; `connect_timeout:` and `stream_idle_timeout:` apply to streams. A per-request `timeout:` overrides them for one call. The total timeout covers connecting, sending and reading the whole body. A `Retry-After` of zero, a negative one or a date in the past is treated as absent: the SDK waits its normal back-off instead of retrying at once.
+
+## Pagination
+
+List operations use cursor pagination (`{ data, next_cursor }`). The plain method returns one typed page that knows whether there is a next page and can fetch it. The auto-paging variant is a lazy iterator: it requests the next page only when needed, carries your filters over, and stops fetching as soon as you stop iterating.
+
+```ruby
+page = client.proposals.list(status: "previewed", limit: 50)
+page.data.each { |proposal| puts proposal.title }
+page = page.next_page if page.next_page?
+
+client.proposals.list_all(status: "previewed").each do |proposal|
+  puts "#{proposal.id} #{proposal.total.formatted}"
+end
+
+first_ten = client.proposals.list_all.first(10)
+puts first_ten.size
+```
+
+`*_all` returns a plain `Enumerator`, so `first`, `take_while`, `lazy` and friends work and fetch only the pages they need. If the API ever returns a cursor it has already returned during the walk (not only the previous one), a `Tungo::PaginationError` is raised instead of looping forever.
+
+## Streaming
+
+Streaming operations use server-sent events and deliver typed events as they arrive. Leaving the loop early or closing the stream closes the connection. A stream request is retried only before its first byte; an error response is raised as the same typed API error as for ordinary calls. A chat stream that ends before its final event is reported as an error, never as a finished answer.
+
+```ruby
+stream = client.chat.create_stream(message: "Сколько НДС к уплате за III квартал?")
+turn = stream.each_text { |delta| print delta }
+puts
+puts "dialog #{turn.dialog_id}, turn #{turn.turn_no}, stop reason #{turn.stop_reason}"
+
+# Or handle every typed event yourself; leaving the block closes the connection.
+client.chat.create_stream(message: "Привет").each do |event|
+  case event
+  when Tungo::Models::ChatEventText then print event.delta
+  when Tungo::Models::ChatEventTool then puts "[#{event.name}]"
+  when Tungo::Models::ChatEventDone then break
+  end
+end
+```
+
+All five streaming operations work the same way: `chat.create_stream`, `chat.answer_stream`, `chat.list_events`, `batches.list_events` (typed `ChatEvent` variants, as a `Tungo::ChatStream`) and `feed.list_events` (`FeedItem` objects). Heart-beats are skipped; `each_sse` yields the raw events instead. `accumulate` and `each_text` raise the typed `Tungo::APIError` if the turn reports an error, and `Tungo::DecodeError` ("stream ended before completion") if the stream ends with neither a `done` nor an `error` event, so a cut answer never looks like a finished turn; plain `each` simply ends. A success answer whose `Content-Type` is not `text/event-stream` raises `Tungo::DecodeError` when the stream is opened. A stream can be consumed once; it may be handed to another thread and read or closed there (each request runs on a worker thread of the transport), but not read by two threads at once. Pass `last_event_id:` to resume the pure event streams.
+
+## Webhooks
+
+Outgoing webhooks are signed according to the Standard Webhooks specification (Svix). The verify helper takes the raw request body and the headers (`webhook-*` or `svix-*`), checks the HMAC-SHA256 signature in constant time and the timestamp within 300 s of the system clock, and returns the typed event. Any problem is reported as a webhook verification error. If no secret is passed, the client's webhook secret is used.
+
+The send-hook helper posts an event to an incoming hook (`/hooks/{token}`) and, when given a secret, signs the exact bytes it sends in the `X-Signature: sha256=<hex>` header. The API key is never sent to hooks.
+
+```ruby
+# In a Rack or Rails endpoint: pass the raw body and the request headers.
+event = client.verify_webhook(request.body.read, request.env)
+case event
+when Tungo::Models::WebhookEventProposalWritten
+  puts "Proposal #{event.data.proposal_id} was written"
+else
+  puts "Unhandled event #{event.type}"
+end
+
+# Send an event to an incoming hook, signed with the hook's secret.
+accepted = client.send_hook("th_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+                            { id: "order_1532", amount_tiyn: 4_500_000 }, secret: "hksec_secret")
+puts accepted.event_id
+```
+
+`Tungo::Webhooks.verify_webhook(payload, headers, secret)` does the same without a client. Headers can be a Hash, a Rack env or any header collection. `Tungo::Webhooks.verify_hook_signature(body, signature, secret)` checks the `X-Signature` of an incoming hook on your side.
+
+## Money
+
+The API expresses amounts in tiyn (1/100 of a tenge) as 64-bit integers. The money helper converts decimal strings and exact decimal values to tiyn without floating-point error, rounding half away from zero (`"1.005"` → `101`), and formats tiyn for display (`4500000` → `45 000,00 ₸`). Invalid input raises a typed error.
+
+```ruby
+Tungo::Money.to_tiyn("1.005") # => 101
+Tungo::Money.to_tiyn(BigDecimal("45000.5")) # => 4_500_050
+Tungo::Money.format_tiyn(4_500_000) # => "45 000,00 ₸"
+Tungo::Money.format_tiyn(-50, "USD") # => "-0,50 $"
+Tungo::Money.to_tenge(4_500_050) # => BigDecimal("45000.5")
+Tungo::Money.valid_bin_iin?("990140000017") # => true
+```
+
+Numbers with a fraction in API responses (such as `Money#amount`) are parsed as `BigDecimal`, never as `Float`, and a `BigDecimal` you pass in is sent digit for digit. `to_tiyn` also accepts `Integer`, `Rational` and, for convenience, `Float` (converted through its shortest decimal representation). Invalid input raises `Tungo::MoneyError`.
+
+## Models
+
+Every schema of the contract is a class under `Tungo::Models`: an immutable value object with typed readers.
+
+```ruby
+company = client.companies.get
+company.name                # typed reader
+company[:some_new_field]    # a field this SDK version does not know yet
+company.key?(:bin)          # present (even when null) or absent?
+company.to_h                # plain Ruby data with symbol keys
+company.to_json             # exactly what travels on the wire
+```
+
+Enumerations are modules with one constant per known value (`Tungo::Models::ProposalStatus::PREVIEWED`); the readers return plain strings, so a value added by a newer API passes through. Unions with a discriminator (`ChatEvent`, `WebhookEvent`, ...) decode to the matching variant class and to `Tungo::UnknownVariant` for a variant this version does not know.
+
+## Long-running helpers
+
+```ruby
+run = client.run_scenario_and_wait("scn_01h455vb4pex5vsknk084sn02q", timeout: 300)
+puts run.state
+
+job = client.upload_bank_statement(Pathname("kl_to_1c.txt"))
+job = client.wait_for_batch(job.id)
+puts job.running
+```
+
+The wait helpers poll with a pause that grows from 1 s to 5 s and raise `Tungo::WaitTimeoutError` (a `Tungo::TimeoutError`) when the deadline (`timeout:`, 600 s by default) passes. `send_hook` and `automations.post_hook` send the `event_id` you pass as the `Idempotency-Key`, and a random UUID when you pass none.
+
+## API reference
+
+Generated from the Tungo Platform API contract: **13 resources, 82 methods, 22 webhook event types**.
+
+| Resource | Description | Methods |
+| --- | --- | --- |
+| `client.workspaces` | Organisations (workspaces) the API key can access | `list` |
+| `client.companies` | Companies of an organisation and their profiles | `list` · `get` |
+| `client.platform` | Platform balance, ledger, usage reports, limits, audit log and model rates | `list_usage_rates` · `get_account` · `get_audit / get_audit_all` · `get_ledger / get_ledger_all` · `list_limits` · `list_requests / list_requests_all` · `get_usage` |
+| `client.api_keys` | The current API key and its usage statistics | `get_current` · `get_current_usage` · `get_usage` |
+| `client.webhooks` | Outgoing webhooks of an organisation (Svix): endpoints, event catalogue, deliveries and signature check | `list_endpoints / list_endpoints_all` · `create_endpoint` · `get_endpoint` · `update_endpoint` · `delete_endpoint` · `list_endpoint_attempts / list_endpoint_attempts_all` · `rotate_endpoint_secret` · `test_endpoint` · `list_event_types` · `list_messages / list_messages_all` · `list_message_attempts / list_message_attempts_all` · `resend_message` · `get_usage` |
+| `client.chat` | Conversations with the AI accountant: questions, streaming chat (SSE), token counting and history | `list / list_all` · `create / create_stream` · `count_tokens` · `get` · `update` · `delete` · `answer / answer_stream` · `list_events` · `stop` |
+| `client.proposals` | Documents proposed by the AI accountant: review, approval for posting to 1C, and rejection | `list / list_all` · `approve_batch` · `get` · `approve` · `reject` |
+| `client.feed` | The company's feed of events and proposals (pages and a live SSE stream) | `get / get_all` · `list_events` |
+| `client.batches` | Processing batches for bank statements, incoming e-invoices and DirectBank | `list / list_all` · `create_bank_statement` · `create_esf_purchases` · `get` · `list_events` · `stop` · `get_summary` · `list_statements / list_statements_all` · `poll_directbank` |
+| `client.esf` | Incoming and outgoing electronic invoices (the ESF system) | `get_incoming / get_incoming_all` · `get_outgoing / get_outgoing_all` |
+| `client.forms` | Tax forms (FNO 100.00 and others): building, ISNA checks and data gaps | `list` · `build` · `list_data_gaps` · `get_isna` · `list_notes` |
+| `client.onec` | Status of the company's connection to its 1C database | `get_status` |
+| `client.automations` | Company automations: incoming hooks, scenarios, step chains, runs and the AI autonomy level | `post_hook` · `list_hooks` · `create_hook` · `get_hook` · `update_hook` · `delete_hook` · `rotate_hook` · `test_hook` · `list_runs / list_runs_all` · `get_run` · `cancel_run` · `retry_run` · `list_scenarios` · `create_scenario` · `get_scenario` · `put_scenario` · `update_scenario` · `delete_scenario` · `run_scenario` · `get_state` · `put_state` · `get_autonomy` · `put_autonomy` |
+
+## Other SDKs
+
+The same API is available in ten languages. All SDKs are generated from one contract and behave the same way.
+
+| Language | Repository | Package |
+| --- | --- | --- |
+| TypeScript | [tungo-sdk-typescript](https://github.com/TungoAI/tungo-sdk-typescript) | `@tungoai/sdk` |
+| Python | [tungo-sdk-python](https://github.com/TungoAI/tungo-sdk-python) | `tungoai` |
+| Go | [tungo-sdk-go](https://github.com/TungoAI/tungo-sdk-go) | `github.com/TungoAI/tungo-sdk-go` |
+| Rust | [tungo-sdk-rust](https://github.com/TungoAI/tungo-sdk-rust) | `tungo-sdk` |
+| PHP | [tungo-sdk-php](https://github.com/TungoAI/tungo-sdk-php) | `tungo/sdk` |
+| Java | [tungo-sdk-java](https://github.com/TungoAI/tungo-sdk-java) | `kz.tungo:tungo-sdk` |
+| Kotlin | [tungo-sdk-kotlin](https://github.com/TungoAI/tungo-sdk-kotlin) | `kz.tungo:tungo-sdk-kotlin` |
+| Swift | [tungo-sdk-swift](https://github.com/TungoAI/tungo-sdk-swift) | `TungoSDK` |
+| **Ruby** | [tungo-sdk-ruby](https://github.com/TungoAI/tungo-sdk-ruby) | `tungo-sdk` |
+| .NET | [tungo-sdk-dotnet](https://github.com/TungoAI/tungo-sdk-dotnet) | `Tungo.Sdk` |
+
+## Versioning and support
+
+This library follows [Semantic Versioning](https://semver.org/). While the major version is 0, a minor release may contain breaking changes; they are always listed in the [changelog](https://github.com/TungoAI/tungo-sdk-ruby/blob/main/CHANGELOG.md). This README describes version 0.2.0.
+
+The code is generated: please report problems and ideas in the [issue tracker](https://github.com/TungoAI/tungo-sdk-ruby/issues) rather than opening pull requests against generated files. To report a vulnerability, follow the [security policy](https://github.com/TungoAI/tungo-sdk-ruby/blob/main/SECURITY.md).
+
+## License
+
+[MIT](https://github.com/TungoAI/tungo-sdk-ruby/blob/main/LICENSE)

data/SECURITY.md

@@ -0,0 +1,19 @@
+# Security policy
+
+## Supported versions
+
+Security fixes are released for the latest minor version of the Tungo SDK for Ruby. Upgrade to the newest release before reporting a problem.
+
+## Reporting a vulnerability
+
+Please do not open a public issue for a security problem.
+
+Report it privately through GitHub: https://github.com/TungoAI/tungo-sdk-ruby/security/advisories/new
+
+Include the SDK version, the runtime version, and the smallest example that shows the problem. Never include a real API key or webhook secret in a report; if a key was exposed, revoke it in the Tungo console first.
+
+You will get an acknowledgement within five working days. We will agree on a disclosure date with you and credit you in the release notes unless you prefer otherwise.
+
+## Scope
+
+This policy covers the code in this repository. Problems in the Tungo API itself should be reported the same way; they will be routed to the platform team.

data/lib/tungo/api_response.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Tungo
+  # The rate-limit headers of one response.
+  #
+  # @!attribute limit
+  #   @return [Integer, nil] requests allowed in the current window (+x-ratelimit-limit+)
+  # @!attribute remaining
+  #   @return [Integer, nil] requests left in the current window (+x-ratelimit-remaining+)
+  # @!attribute reset
+  #   @return [Integer, nil] seconds until the next window (+x-ratelimit-reset+)
+  RateLimit = Data.define(:limit, :remaining, :reset) do
+    # @return [Tungo::RateLimit, nil] nil when the response carries none of the headers
+    def self.from_headers(headers)
+      values = %w[x-ratelimit-limit x-ratelimit-remaining x-ratelimit-reset].map do |name|
+        text = headers[name].to_s.strip
+        text.match?(/\A-?[0-9]+\z/) ? text.to_i : nil
+      end
+      values.all?(&:nil?) ? nil : new(*values)
+    end
+  end
+
+  # Status and headers of the HTTP response behind a result. Every result exposes it:
+  # {Tungo::Model#api_response}, {Tungo::Page#api_response}, {Tungo::Stream#api_response};
+  # operations without a response body return it directly.
+  #
+  # @!attribute status
+  #   @return [Integer] HTTP status
+  # @!attribute headers
+  #   @return [Hash{String=>String}] response headers with lower-case names
+  APIResponse = Data.define(:status, :headers) do
+    # @return [String, nil] the value of a header, looked up case-insensitively
+    def [](name)
+      headers[name.to_s.downcase]
+    end
+
+    # @return [String, nil] the request id to quote to support (+x-request-id+)
+    def request_id
+      headers["x-request-id"]
+    end
+
+    # @return [Tungo::RateLimit, nil] the rate-limit headers of this very response
+    def rate_limit
+      RateLimit.from_headers(headers)
+    end
+
+    # @return [Boolean] true when the API replayed a stored response for a repeated Idempotency-Key
+    def idempotent_replayed?
+      headers["idempotent-replayed"] == "true"
+    end
+  end
+end