Repository navigation
Releases
keenable (TypeScript) 0.1.5
search()acceptsexcludeDomains: a list of hosts to keep out of the
results. A host also excludes its subdomains; up to 1,000 distinct hosts. Any
iterable of strings (an array, aSet) is sent as an array of its entries as
given, including[]; a lone string is one host, and""is sent as[""]
so the API rejects it rather than searching unfiltered. The API cleans up
unambiguous entries (scheme,www., case, port, trailing/or dot, query,
#fragment, whitespace; international names become punycode) and rejects
anything else (paths, suffixes such as.com, wildcards, IP addresses,
user@host, invalid hosts) with HTTP 400. If every result is excluded, the
response can be empty.siteis unchanged.- The
keenable_searchtool offersexclude_domainsalongsidesite.
runToolCallsends the argument as given: only an absent ornullvalue (or
"") is unset, a lone string is wrapped, and any other value goes to the
API, which rejects a malformed one with a 400. - A rejected entry is a 400 whose
param,valueandreasonname it, and
whose message ends with the API'sfix.valueandreasonare set only
when the body'serrorisinvalid_filter,undefinedotherwise.value
is usually the entry as sent; a size cap reports the list's size
("2500 entries"or"more than 1000 distinct hosts") or an over-long
entry's first 64 characters and"...". - A search argument JSON cannot encode (a
BigInt) throws
KeenableInvalidRequestErrorand sends nothing, insearch()and
runToolCallalike.
The SDK now matches the Python and Go SDKs case for case: all three run the
shared cases in scripts/conformance. Changes marked Behaviour change alter
what an existing call does.
-
Fixed:
Page.publishedAtis now set for fetched pages. The API sends a
fetch's publish date as Unix seconds, which the SDK dropped; it is now an
ISO 8601 UTC string to the second, such as"2024-05-01T12:00:00Z", the
form search results use. An ISO 8601 string is still kept as sent, so both
forms work. The same applies toSearchResult.publishedAtand
acquiredAt. A number below 1, past the year 9999 (a millisecond value
too) or not finite isundefined, as before. -
Added:
Page.truncated(boolean | undefined) andPage.totalChars
(number | undefined): whether the API cutcontentatmax_chars, and
the full content's length in code points.undefinedwhen the API leaves
them out or sends another type.contentandtoContext()are unchanged. -
Added:
search()acceptsmode: "realtime", the fastest response, for
latency-sensitive agent loops."pro", deeper retrieval, stays the default.
The API already took it; the type was"pro"alone. -
Added:
fetch()takesmaxChars(cap the content returned; the API
default is 50000),live(truefetches the page from its source instead
of the indexed copy) andprompt(an extraction instruction of up to 2000
characters;contentis then only the model's output for it). Its second
argument is now the exportedFetchOptions, which extendsRequestOptions,
so existing calls compile unchanged. An option left unset is not sent,
live: falseis not sent, and an emptypromptis unset. -
Added:
search()takesdisableCards:truereturns ordinary web pages
in place of Keenable's cards (results Keenable writes for prices, exchange
rates or company facts, whose URLs expire after one day). It works in the
"pro"and"realtime"modes. Onlytrueis sent:false, the API
default, is left out. A value that is not a boolean throws
KeenableInvalidRequestErrorand sends nothing. Thekeenable_searchtool
offersdisable_cardsas a boolean;runToolCallsends it only astrue,
treatsfalse,nulland""as unset, and rejects any other value. -
Behaviour change: errors no longer expose
docsUrl,billingUrl,
autoTopUpUrl,payPerRequestorraw, and the message no longer ends with
Docs: <url>. None of these was in a release.body(the API's message) is
unchanged. -
Behaviour change: a 402's message is the SDK's own sentence rather than
the API's text, which links to billing and checkout pages:
"Keenable: insufficient credits (402). ..." or, for an x402 orpayment_*
response, "Keenable: payment required (402). This SDK does not pay per
request ...". It is still aKeenableInsufficientCreditsError, withcode,
fix,requestIdandbodyset, and carries no payment offer. -
Behaviour change:
fetch()refuses more special-purpose addresses, the
same list in every SDK:100.64.0.0/10(carrier-grade NAT, including Alibaba
Cloud's metadata address),192.0.0.0/24,192.0.2.0/24,198.18.0.0/15,
198.51.100.0/24,203.0.113.0/24, and every IPv6 address outside
2000::/3or inside2001::/23,2001:db8::/32,2002::/16or3fff::/20
(sofc::1, NAT6464:ff9b::/96,fec0::/10and IPv4-compatible
addresses). It also refuses names under.localhost. -
Behaviour change:
fetch()refuses a URL whose host other parsers read
differently:https:///host,https:hostandhttps:/host(read as
https://host/before), a backslash in the host part, a control character
anywhere, or a leading or trailing space. -
Behaviour change: a
Retry-Afterdate must be one of the three RFC 9110
forms with the zoneGMT. A date with a numeric zone (+0000) or none at all
is ignored and the backoff applies, as in Go. -
Behaviour change: an error body that is JSON but not an object (
"oops",
42,null) no longer becomes the error's detail; the error maps by status
alone. -
Behaviour change: a search result's
title,urlandsnippet, and a
page'stitleandcontent, are""when the API sends something other
than a string (they were"42","[object Object]"or"false"). An array
insideresultsis skipped like any other non-object. -
Behaviour change: a
fetchyou pass that follows a redirect although the
SDK asks it not to (redirect: "manual") now throws the same, non-retried
redirect error instead of returning the other host's reply. -
Behaviour change: a header name that is not an HTTP token, or a value
with CR, LF or NUL, indefaultHeadersor a call'sheaders, throws
KeenableInvalidRequestErrorbefore anything is sent, rather than failing as
a connection error that was retried. -
Behaviour change:
mode: ""sends"pro", and an empty string filter
(such assite: "") is not sent, as in Go. -
Behaviour change:
baseUrlwith a query or fragment is refused (the path
was appended after it), surrounding whitespace is ignored,localhost.counts
as localhost, andhttp://127.1is refused as in Python and Go. A blank
KEENABLE_API_URLmeans the default instead of throwing. -
Behaviour change:
limit.maxis set only for an integer from 0 to
2^53 - 1. -
Fix: a
timeoutMsover 2147483647 (about 24.8 days) timed out at once,
because a JavaScript timer fires immediately past that. It now waits that
long. -
Automatic retries. Connection errors, timeouts, 408, 429 and 5xx are retried
up tomaxRetriestimes (default 2), unless the API marks the error
retryable: false. The wait is the API'sRetry-Afterwhen sent, else
exponential backoff (0.5 s to 8 s, jittered). ARetry-Afterover 60 s, such
as the keyless hourly cap, is thrown at once instead of waited out. Pass
maxRetries: 0to turn retries off. Abortingsignalcancels a pending
retry. -
New
KeenableTimeoutError, aKeenableConnectionErrorsubclass, for a
request that did not answer withintimeoutMs. -
search()andfetch()taketimeoutMs,maxRetriesandheadersfor
that call (the newRequestOptionstype); the client takesmaxRetriesand
defaultHeaders.X-API-Keycan only come fromapiKey. -
SearchResponse.requestIdandPage.requestId(bodyrequest_id, else the
X-Request-Idheader). -
Fix:
fetch()refused every hostname starting withfc,fdor
fe8-feb(such asfdic.govorfcbarcelona.com) as a "private
address". Only IPv6 literals in those ranges are refused now, and IPv4
multicast, reserved and broadcast addresses are refused as in Python and Go. -
Fix: redirects are no longer followed.
fetchwould have carried the
X-API-Keyheader to whatever host a redirect named. A redirect now throws
KeenableConnectionError. -
timeoutMsandmaxRetriesare validated: a non-positive timeout or a
negative or fractional retry count throwsKeenableInvalidRequestError. -
Fix: a
Retry-Afterheader that is not a number or an HTTP date (1.5,
-1,Jan 1) was read as a date in the past, so the retry came at once. It
is now ignored, and the backoff applies, as in Python and Go. -
Fix: a call whose
signalis already aborted throws without calling
fetch, even a customfetchthat ignores the signal. -
Fix:
Page.urlfalls back to the URL you asked for when the API sends an
empty one, as in Python and Go. -
Errors carry the API's agent-ready fields:
code,error,fix,
retryable,retryAfterSeconds(from the body, else theRetry-After
header),requestId(body, elseX-Request-Id),paramandlimit(a new
RateLimitInfotype). Each isundefinedwhen the API does not send it. -
New
KeenableInsufficientCreditsError(aliasKeenableCreditsError) for HTTP 402. It extends
KeenableAPIError, so existing handlers keep working. -
A 403 whose
codeistarget_blocked(the fetched site refused us) is now a
plainKeenableAPIErrorlabelled "Keenable API error (403)" rather than a
KeenableAuthError. Without acode, 401/403 behave as before. -
When the API sends
fix, the error message ends with it (". "), as in
the Go and Python SDKs. ARetry-Afterheader is capped at a year, so an
oversi...
keenable (Python) 0.1.5
Install from GitHub
pip install https://github.com/keenableai/keenable-sdk/releases/download/python-v0.1.5/keenable-0.1.5-py3-none-any.whlkeenable (Python) 0.1.4
search()(sync and async) acceptsexclude_domains: a list of hosts to
keep out of the results. A host also excludes its subdomains; up to 1,000
distinct hosts. Any iterable of strings is sent as a list of its entries as
given, including[]; a lone string is one host, and""is sent as[""]
so the API rejects it rather than searching unfiltered. The API cleans up
unambiguous entries (scheme,www., case, port, trailing/or dot, query,
#fragment, whitespace; international names become punycode) and rejects
anything else (paths, suffixes such as.com, wildcards, IP addresses,
user@host, invalid hosts) with HTTP 400. If every result is excluded, the
response can be empty.siteis unchanged.- The
keenable_searchtool offersexclude_domainsalongsidesite.
run_tool_callsends the argument as given: only an absent ornullvalue
(or"") is unset, a lone string is wrapped, and any other value goes to the
API, which rejects a malformed one with a 400. - A rejected entry is a 400 whose
param,valueandreasonname it, and
whose message ends with the API'sfix.valueandreasonare set only
when the body'serrorisinvalid_filter,Noneotherwise.valueis
usually the entry as sent; a size cap reports the list's size
("2500 entries"or"more than 1000 distinct hosts") or an over-long
entry's first 64 characters and"...". - A search argument JSON cannot encode (
NaN, bytes, an arbitrary object)
raisesKeenableInvalidRequestErrorand sends nothing, insearch()and
run_tool_callalike.
The Python, TypeScript and Go SDKs now run one shared set of conformance cases
(scripts/conformance/), and these changes make them behave the same.
Behaviour changes are marked Changed.
-
Fixed:
Page.published_atis now set for fetched pages. The API sends a
fetch's publish date as Unix seconds, which the SDK dropped; it is now an
ISO 8601 UTC string to the second, such as"2024-05-01T12:00:00Z", the
form search results use. An ISO 8601 string is still kept as sent, so both
forms work. The same applies toSearchResult.published_atand
acquired_at. A number below 1, past the year 9999 (a millisecond value
too), not finite, or a boolean isNone, as before. -
Added:
Page.truncated(bool | None) andPage.total_chars
(int | None): whether the API cutcontentatmax_chars, and the full
content's length in code points.Nonewhen the API leaves them out or
sends another type.contentandto_context()are unchanged. -
Added:
search()acceptsmode="realtime", the fastest response, for
latency-sensitive agent loops."pro", deeper retrieval, stays the default.
The API already took it; the type wasLiteral["pro"]. -
Added:
fetch()takesmax_chars(cap the content returned; the API
default is 50000),live(Truefetches the page from its source instead
of the indexed copy) andprompt(an extraction instruction of up to 2000
characters;contentis then only the model's output for it), onKeenable
andAsyncKeenable. An option left unset is not sent,live=Falseis not
sent, and an emptypromptis unset. -
Added:
search()(sync and async) takesdisable_cards:Truereturns
ordinary web pages in place of Keenable's cards (results Keenable writes for
prices, exchange rates or company facts, whose URLs expire after one day).
It works in the"pro"and"realtime"modes. OnlyTrueis sent:
False, the API default, is left out. Any value that is not aboolraises
KeenableInvalidRequestErrorand sends nothing. Thekeenable_searchtool
offersdisable_cardsas a boolean;run_tool_callsends it only as
true, treatsfalse,nulland""as unset, and rejects any other value. -
Changed: errors no longer have
docs_url,billing_url,
auto_top_up_url,pay_per_requestorraw(none was in a release), and
str(err)no longer ends withDocs: <url>. The SDK does not expose docs
links, billing or checkout URLs, or x402 payment offers. -
Changed: a 402's message is the SDK's own sentence, without the API's
text orfix: "Keenable: payment required (402). This SDK does not pay per
request: ..." for a pay-per-request (x402) orpayment_*response, else
"Keenable: insufficient credits (402). ...". It is still a
KeenableInsufficientCreditsError, andbody,fix,codeand
request_idare still set. -
Changed:
fetch()refuses more targets before sending:100.64.0.0/10
(carrier-grade NAT, including Alibaba Cloud's metadata address),
192.0.0.0/24,fec0::/10,2002::/16,3fff::/20, any IPv6 address
outside2000::/3, names under.localhost, percent-encoded hosts
(127.0.0.%31), hosts with a soft hyphen or zero-width character, URLs with
a control character or surrounding space, a backslash in the host part, or
anything other than exactlyhttp://orhttps://before the host. The
ranges are now a fixed list shared with the other SDKs rather than Python's
ipaddressflags, which differ between Python versions; an IPv4-mapped
public address (::ffff:8.8.8.8) is now allowed on every version. -
Changed: a
Retry-Afterdate must be an RFC 9110 HTTP date
(IMF-fixdate, RFC 850 or asctime, in GMT). A date with a numeric zone or no
zone is ignored, so the next source of the delay (else backoff) is used. -
Changed: an error body field of the wrong type is ignored: a numeric or
objectmessageno longer becomes the detail (str()of it was shown), and
an error body that is JSON but not an object ("oops",42,null) gives
no detail.NaNandInfinityin a body are not JSON, a leading byte order
mark is ignored, and invalid UTF-8 no longer makes a JSON body unreadable. -
Changed: in results and pages, a
title,url,snippetorcontent
that is not a string is""instead of itsstr(); a pageurlthat is
blank or not a string falls back to the URL you fetched. -
Changed:
limit.maxis set only for a whole number from 0 to 2^53 - 1. -
Changed: an invalid header name, or a header value with CR, LF or NUL, in
default_headersorextra_headersraisesKeenableInvalidRequestError
before anything is sent, instead of a connection error that was retried. -
Changed: a non-string
search()query orfetch()URL raises
KeenableInvalidRequestError(wasAttributeErrororTypeError), and an
empty-string search filter is not sent, as in Go. -
Changed:
base_urlmay not have a query or fragment, surrounding
whitespace is dropped,http://localhost.counts as localhost, and a blank
KEENABLE_API_URLmeans the default. -
Changed: a timeout over 2,147,483.647 s (about 24.8 days) is treated as
that long; a larger one raisedOverflowErrorfrom the socket layer. -
Automatic retries. Connection errors, timeouts, 408, 429 and 5xx are retried
up tomax_retriestimes (default 2), unless the API marks the error
retryable: false. The wait is the API'sRetry-Afterwhen sent, else
exponential backoff (0.5 s to 8 s, jittered). ARetry-Afterover 60 s, such
as the keyless hourly cap, is raised at once instead of waited out. Pass
max_retries=0to turn retries off. -
New
KeenableTimeoutError, aKeenableConnectionErrorsubclass, for a
request that did not answer withintimeout. -
search()andfetch()taketimeout,max_retriesandextra_headers
for that call; the clients takemax_retriesanddefault_headers.
X-API-Keycan only come fromapi_key. -
SearchResponse.request_idandPage.request_id(bodyrequest_id, else
theX-Request-Idheader). -
Redirects are never followed, even by an
httpx.Clientyou pass with
follow_redirects=True, so the API key cannot reach another host. A
redirect raisesKeenableConnectionError. -
With your own
client, its timeout now applies unless you passtimeout;
before, the SDK's 30 s default was ignored silently either way.
On the client,timeout=Nonestill means no deadline. A per-calltimeout
overrides the client's for that call, and a per-callNone(the default)
keeps the client's. Anhttpx.Timeoutis accepted in both places. -
timeoutandmax_retriesare validated: a non-positive timeout or a
negative retry count raisesKeenableInvalidRequestError. -
Fix: a retry budget over 1024 raised
OverflowErrorin the backoff. -
Fix:
fetch()now refuses a loopback or private host spelled as a number
(2130706433,0x7f.0.0.1,0177.0.0.1,127.1) or in fullwidth digits,
as the TypeScript SDK does. -
Fix: a whitespace-only
messagein an error body no longer becomes the
error's detail, and a blankqueryin a response keeps the query you sent. -
Errors carry the API's agent-ready fields:
code,error,fix,
retryable,retry_after_seconds(from the body, else theRetry-After
header),request_id(body, elseX-Request-Id),paramandlimit(a
newRateLimitInfo). Each isNonewhen the API does not send it. -
New
KeenableInsufficientCreditsError(aliasKeenableCreditsError) for HTTP 402. It subclasses
KeenableAPIError, so existing handlers keep working. -
A 403 whose
codeistarget_blocked(the fetched site refused us) is now a
plainKeenableAPIErrorlabelled "Keenable API error (403)" rather than a
KeenableAuthError. Without acode, 401/403 behave as before. -
When the API sends
fix, the error message ends with it (". "), as in
the Go and TypeScript SDKs. ARetry-Afterheader is capped at a year, so an
oversized value can never break error handling. The same year cap applies to
a far-futureRetry-Afterdate and to the body'sretry_after_secondsand
retryAfter; a body value too large for a double (such as1e400) is
dropped and the next source of the delay is used, as in the other SDKs. -
Er...
keenable (TypeScript) 0.1.4
search() accepts maxResults (1 to 50) and queryTime. Both are client-only; the tool schema is unchanged. No migration.
keenable (Python) 0.1.3
search() accepts max_results (1 to 50) and query_time. Both are client-only; the tool schema is unchanged. No migration.
keenable (TypeScript) 0.1.3
SearchResult.descriptionandPage.descriptionare marked@deprecated. The API no longer fills them: readsnippeton search results andcontenton fetched pages. The fields stay for compatibility; see https://docs.keenable.ai/versioning.
The Python SDK 0.1.2 ships the same change.
keenable (Python) 0.1.2
SearchResult.descriptionandPage.descriptionare deprecated. The API no longer fills them: readsnippeton search results andcontenton fetched pages. The fields stay for compatibility; see https://docs.keenable.ai/versioning.
The TypeScript SDK 0.1.3 ships the same change.
keenable (TypeScript) 0.1.2
Published to npm on 2026-09-07. This GitHub release was added on 2026-10-29 because the tag was missing.
keenable (TypeScript) 0.1.1
Hardening and internals release. No breaking changes.
Fixed
- SSRF guard: the client-side fetch precheck missed IPv4-mapped IPv6 addresses, so
https://[::ffff:169.254.169.254]/reached the network, cloud-metadata address included. Note the detail that made this easy to miss:new URL()rewrites the dotted tail into hex (::ffff:a9fe:a9fe), so a check that only knows the dotted spelling never fires. A trailing dot in the host (https://localhost./) is now normalised away too. toContext()stopped at the first over-budget result rather than skipping it and continuing, which could emit[1]then[3]and break the mapping from a model's citations back to results. Now pinned by a test.- Non-object tool-call arguments (an array, a number) are rejected as
KeenableInvalidRequestErrorinstead of silently becoming "no query".
Added
SearchResponse.cited()reports which resultstoContext()actually rendered, in citation order, so a printed source list cannot number sources the model never saw.Page.toContext(): a fetched page renders as the same numbered, citable block as search results, and thekeenable_fetchtool now returns it instead of anonymous markdown.clientSourcelets an integration built on this SDK keep its own traffic attribution instead of forking the transport.
Changed
toContext()collapses whitespace in snippets. They are raw page text, and their newlines collided with the blank line that separates one source from the next.- The package version is injected at build time from
package.json, so the User-Agent cannot go stale. - Internals: endpoints named once with the keyless
/publicvariant derived, and the search filters declared in one table that the payload builder, the tool schema and the tool dispatcher all read.
Published to npm: https://www.npmjs.com/package/keenable
keenable (TypeScript) 0.1.0
First release of the Keenable TypeScript SDK.
npm install keenableimport { Keenable } from "keenable";
const keenable = new Keenable(); // keyless; KEENABLE_API_KEY only lifts the rate limit
const results = await keenable.search("fastest inference providers 2026");
console.log(results.toContext());search()withsite, publication-date and index-date filters,snippetMaxLength, and anAbortSignalfetch()returning any URL as markdowntoContext(), which renders results as a numbered, citable block for a promptTOOLS+runToolCall(): OpenAI-compatible tool definitions and a dispatcher for tool calling- Node 18+, no runtime dependencies, ESM and CJS with types
Published manually to npm: https://www.npmjs.com/package/keenable