Skip to main content

portaki_connectors/
lib.rs

1//! Typed clients for Portaki built-in external connectors.
2//!
3//! # Role in the SDK stack
4//!
5//! `portaki-connectors` sits beside [`portaki_sdk`]: modules depend on both.
6//! [`portaki_sdk::host::connectors::call`] is the low-level host dispatch
7//! (serialize args → JSON egress → deserialize response). This crate wraps that
8//! dispatch with provider-specific types, operation names, and response parsing.
9//!
10//! Modules never perform raw HTTP. They either:
11//!
12//! 1. Call types here (e.g. [`OpenWeather::current`]) from domain code, or
13//! 2. Declare connector metadata in their manifest via `#[portaki_sdk::custom_connector]`
14//!    while still using these types at runtime.
15//!
16//! Credential validation helpers ([`OpenWeather::validate_credentials`], etc.) are
17//! **local format checks** used during module install / BYOK configuration — they
18//! do not call the provider network.
19//!
20//! # Connector IDs and operations
21//!
22//! Each submodule maps 1:1 to a host connector id and its operation strings:
23//!
24//! | Module | `connector_id` | Operations |
25//! |--------|----------------|------------|
26//! | [`open_weather`] | `open-weather` | `current`, `forecast`, `historical` |
27//! | [`open_agenda`] | `open-agenda` | `nearby_events` |
28//! | [`google_places`] | `google-places` | `nearby_search`, `text_search`, `details`, `photos` |
29//! | [`mapbox`] | `mapbox` | `geocode`, `reverse_geocode`, `directions`, `static_map` |
30//! | [`osm_nominatim`] | `osm-nominatim` | `geocode`, `reverse_geocode` |
31//! | [`nuki`] | `nuki` | `remote_unlock` |
32//! | `tiqets` | `tiqets` | `nearby_products` — **déprécié**, voir ci-dessous |
33//! | `viator` | `viator` | `search_products` — **déprécié**, voir ci-dessous |
34//!
35//! # Ce qui n'a pas sa place ici
36//!
37//! Ce crate ne porte que des connecteurs **catalogués par la plateforme** : elle en résout les
38//! identifiants, en accorde les capacités et en garde les clés. Un connecteur qu'un module
39//! déclare lui-même (ADR-0021) n'y a rien à faire — ses types et son analyse lui appartiennent,
40//! et les mettre ici met son travail derrière une release du SDK pour rien.
41//!
42//! `tiqets` et `viator` sont dans ce cas, par héritage : la plateforme n'accorde plus de capacité
43//! pour eux (leurs [`portaki_sdk::capability::CapabilityId`] le disent déjà), `local-guide` les a
44//! rapatriés, et **plus rien ici ne les consomme**. Ils partiront en 10.0, et `portaki add
45//! connector` ne les propose plus — ils ont quitté la liste des connecteurs intégrés, qu'un test
46//! épingle sur le tableau ci-dessus.
47//!
48//! Pas de `#[deprecated]` dessus, et ce n'est pas un oubli : l'attribut sur un module fait rougir
49//! les constantes que `#[test]` engendre dans ses propres tests, et aucun `allow` ne les couvre.
50//! On perdrait la couverture de code qui tourne encore en 9.x pour avertir des appelants qui
51//! n'existent plus. La note ci-dessus et la dépréciation des capacités disent la même chose.
52//!
53//! The gateway resolves credentials (platform pool or BYOK) from the invocation
54//! [`portaki_sdk::context::Context`] capabilities before executing egress.
55//!
56//! # Usage
57//!
58//! ```no_run
59//! use portaki_connectors::open_weather::{CurrentArgs, OpenWeather};
60//! use portaki_sdk::host::{self, HostBackend};
61//! use portaki_sdk::context::Context;
62//! use portaki_sdk::PortakiError;
63//! use std::sync::Arc;
64//!
65//! let backend: Arc<dyn HostBackend> = todo!("install backend");
66//! let ctx = Context::default();
67//!
68//! let temp_c = host::with_host(backend, ctx, || -> Result<f64, PortakiError> {
69//!     let weather = OpenWeather::current(&CurrentArgs { lat: 43.55, lng: 7.01 })?;
70//!     Ok(weather.temp_c)
71//! })?;
72//! # Ok::<(), PortakiError>(())
73//! ```
74//!
75//! # Testing
76//!
77//! Each connector carries canned responses for its operations ([`open_weather::MOCK_RESPONSES`],
78//! …), aggregated by [`mod@mock`]. `portaki-test-utils` mounts them all with
79//! `MockContextBuilder::with_builtin_connectors()`; `with_connector_response` still overrides
80//! any single operation.
81//!
82//! They are behind the `mock` feature, off by default, so they are compiled out of a module's
83//! published Wasm rather than merely unused — see [`mod@mock`] for the boundary and its proof.
84//!
85//! # Errors
86//!
87//! - Runtime connector failures surface as [`portaki_sdk::PortakiError`] from
88//!   [`portaki_sdk::host::connectors::call`].
89//! - [`ConnectorError`] covers local credential validation only.
90
91#![deny(missing_docs)]
92
93pub mod google_places;
94pub mod mapbox;
95#[cfg(feature = "mock")]
96pub mod mock;
97pub mod nuki;
98pub mod open_agenda;
99pub mod open_weather;
100pub mod osm_nominatim;
101pub mod tiqets;
102pub mod viator;
103
104pub use google_places::GooglePlaces;
105pub use mapbox::Mapbox;
106pub use nuki::Nuki;
107pub use open_agenda::OpenAgenda;
108pub use open_weather::OpenWeather;
109pub use osm_nominatim::OsmNominatim;
110pub use tiqets::Tiqets;
111pub use viator::Viator;
112
113/// Local validation failure for connector credentials (install-time / BYOK checks).
114///
115/// Distinct from [`portaki_sdk::PortakiError`]: returned only by
116/// `validate_credentials` helpers in this crate. Does not indicate an egress
117/// or host dispatch failure.
118#[derive(Debug, thiserror::Error)]
119pub enum ConnectorError {
120    /// The supplied API key or token failed the crate-local non-empty check.
121    ///
122    /// Message is provider-specific (e.g. `"open-weather api key is empty"`).
123    #[error("invalid credentials: {0}")]
124    InvalidCredentials(String),
125}
126
127/// Result alias for [`ConnectorError`].
128///
129/// Used by `validate_credentials` methods. Connector runtime calls return
130/// [`portaki_sdk::Result`] instead.
131pub type Result<T> = std::result::Result<T, ConnectorError>;