unitysvc-core 0.3.3__tar.gz → 0.3.5__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. {unitysvc_core-0.3.3/src/unitysvc_core.egg-info → unitysvc_core-0.3.5}/PKG-INFO +25 -3
  2. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/README.md +24 -2
  3. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/pyproject.toml +1 -1
  4. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/src/unitysvc_core/grants.py +94 -14
  5. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/src/unitysvc_core/models/base.py +9 -0
  6. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/src/unitysvc_core/models/channel.py +4 -2
  7. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/src/unitysvc_core/models/offering_data.py +6 -3
  8. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/src/unitysvc_core/models/offering_v1.py +21 -6
  9. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/src/unitysvc_core/models/validators.py +71 -5
  10. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/src/unitysvc_core/schema/offering_v1.json +24 -20
  11. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/src/unitysvc_core/validator.py +32 -4
  12. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5/src/unitysvc_core.egg-info}/PKG-INFO +25 -3
  13. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/src/unitysvc_core.egg-info/SOURCES.txt +1 -0
  14. unitysvc_core-0.3.5/tests/test_external_apps.py +159 -0
  15. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/tests/test_grants.py +137 -0
  16. unitysvc_core-0.3.5/tests/test_offering_data.py +26 -0
  17. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/tests/test_validators.py +9 -0
  18. unitysvc_core-0.3.3/tests/test_offering_data.py +0 -14
  19. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/LICENSE +0 -0
  20. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/setup.cfg +0 -0
  21. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/src/unitysvc_core/__init__.py +0 -0
  22. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/src/unitysvc_core/models/__init__.py +0 -0
  23. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/src/unitysvc_core/models/documents.py +0 -0
  24. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/src/unitysvc_core/models/listing_data.py +0 -0
  25. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/src/unitysvc_core/models/listing_v1.py +0 -0
  26. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/src/unitysvc_core/models/pricing.py +0 -0
  27. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/src/unitysvc_core/models/promotion_data.py +0 -0
  28. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/src/unitysvc_core/models/provider_data.py +0 -0
  29. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/src/unitysvc_core/models/provider_v1.py +0 -0
  30. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/src/unitysvc_core/models/service.py +0 -0
  31. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/src/unitysvc_core/models/service_group_data.py +0 -0
  32. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/src/unitysvc_core/parameter_usage.py +0 -0
  33. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/src/unitysvc_core/py.typed +0 -0
  34. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/src/unitysvc_core/schema/base.json +0 -0
  35. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/src/unitysvc_core/schema/listing_v1.json +0 -0
  36. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/src/unitysvc_core/schema/promotion_v1.json +0 -0
  37. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/src/unitysvc_core/schema/provider_v1.json +0 -0
  38. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/src/unitysvc_core/schema/service_group_v1.json +0 -0
  39. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/src/unitysvc_core/utils.py +0 -0
  40. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/src/unitysvc_core.egg-info/dependency_links.txt +0 -0
  41. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/src/unitysvc_core.egg-info/requires.txt +0 -0
  42. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/src/unitysvc_core.egg-info/top_level.txt +0 -0
  43. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/tests/test_access_interface_routing.py +0 -0
  44. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/tests/test_canonical_interfaces.py +0 -0
  45. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/tests/test_channel.py +0 -0
  46. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/tests/test_effective_price.py +0 -0
  47. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/tests/test_hidden_path_skip.py +0 -0
  48. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/tests/test_listing_audience.py +0 -0
  49. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/tests/test_parameter_usage.py +0 -0
  50. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/tests/test_pricing.py +0 -0
  51. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/tests/test_provider_account_rate_limits.py +0 -0
  52. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/tests/test_service_group.py +0 -0
  53. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/tests/test_service_status.py +0 -0
  54. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/tests/test_utils.py +0 -0
  55. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/tests/test_validate_service.py +0 -0
  56. {unitysvc_core-0.3.3 → unitysvc_core-0.3.5}/tests/test_validator.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: unitysvc-core
3
- Version: 0.3.3
3
+ Version: 0.3.5
4
4
  Summary: Shared data models and validation helpers for UnitySVC packages
5
5
  Author-email: Bo Peng <bo.peng@unitysvc.com>
6
6
  Maintainer-email: Bo Peng <bo.peng@unitysvc.com>
@@ -208,12 +208,13 @@ Three stages (unitysvc/unitysvc#2720): a target service's **`exports`** (what it
208
208
  "limits": {"count_per_day": 1000}}]
209
209
  ```
210
210
 
211
- - `object` names one service (`service:<name>`, no wildcards), or `apikey` for the leased key's lifespan (below). `permissions` are plain names (lowercase letters, digits and `_`; no wildcards), checked against the target's exports with a catalog.
211
+ - `object` names one service (`service:<name>`, no wildcards), a resource the platform provisions for the enrollment (`resource:room`, below), or `apikey` for the leased key's lifespan (below). `permissions` are plain names (lowercase letters, digits and `_`; no wildcards), checked against the target's exports with a catalog.
212
212
  - `required` (`true` or `false`, on every entry, `apikey` included) says whether the customer may decline the request. A stored declaration from before this rule reads as optional when a policy is built.
213
213
  - `options` is written in query-string syntax (`parse_options`; a notation, not how options are delivered): each name once, each value non-empty; with a catalog, each value is converted to its declared type and validated against the target's `options` schema.
214
214
  - **A request's `options` are fixed.** Every option it declares is in the policy of an approved request, with the declared value; the customer may repeat it but not change or drop it. An option the request does not declare is the customer's to set at enrollment (a form rendered from the target's `options` schema). So `{"object": "service:ai", ...}` lets the customer pick the AI service, and `"options": "service=labs/llm-balanced"` pins it.
215
215
  - Several requests may name one object (two kinds of room) only if each fixes some option to a different value (`kind=chat`, `kind=feed`), so an approval says which one it is.
216
216
  - `limits` (`validate_limits`): `count_per_hour` / `count_per_day` / `count_per_month` / `count_total` (positive integer) and the same for `amount_` (finite positive decimal, as a number or a string). Limits are universal: the platform meters every call, so any service can be limited without exporting anything. The seller's limits only pre-fill the form; the customer sets them at enrollment, and an enrollment's own limits (unitysvc/unitysvc#2687) use the same shape. They are counted per policy entry (the enrollment's calls to that service) from the usage stream (counters keyed by scope, metric and window bucket), and the gateway refuses calls once one is exceeded.
217
+ - **A room the platform provisions** (unitysvc/unitysvc#2830) is asked for with `resource:room`: `{"object": "resource:room", "permissions": ["create"], "required": true, "justification": "Creates your chat room", "options": "kind=chat&max_members=100"}`. Core knows the resource, so no catalog is consulted. The request must fix `kind`, the room's identity; each kind bounds the permissions (`chat`: `create`, a room the customer owns; `support`: `join`, `read`, `post`, the seller's private room with the customer; `announcement`: `join`, `read`; `discussion`: `join`, `read`, `post`). `max_members` (a positive integer) caps only a room the customer creates. A channel requests each kind at most once, and a resource takes no limits.
217
218
  - **A longer-lived leased key** is asked for with one `apikey` entry: `{"object": "apikey", "required": false, "limits": {"api_key_lifespan": 14400}, "justification": "Batch runs take up to four hours"}`. It names the key itself, so it takes only `limits` (exactly `api_key_lifespan`, whole seconds from 1 to 86400), `required` and a `justification`, needs no catalog lookup, and grants nothing. Without it, a key the seller leases for the enrollment lives `DEFAULT_API_KEY_LIFESPAN` (3600 s). `api_key_lifespan` is valid only on this entry.
218
219
 
219
220
  **3. How options reach the service.** Not through the upstream URL: the gateway never changes a target's `base_url` or query to carry policy. How an option is applied is up to the service's implementation:
@@ -259,7 +260,7 @@ A policy has three kinds of entry (unitysvc/unitysvc#2770):
259
260
  | Channel key | What it is |
260
261
  | --- | --- |
261
262
  | `access_method` | `http` (default), `smtp`, `s3` or `mcp`; selects the server type |
262
- | `type` | normally derived by the platform; declare `external` (or `enrollable`) to state it |
263
+ | `type` | normally derived by the platform; declare `enrollable` to state it |
263
264
  | `description`, `is_active`, `sort_order` | display text; inactive channels are skipped; rank, lowest first |
264
265
  | `request_formats`, `applicable_interfaces` | the formats the channel serves; the interfaces that reach it (display only) |
265
266
  | `rate_limit_refs` | the provider rate limits it consumes |
@@ -271,6 +272,27 @@ The common one-server case writes the connection fields directly on the channel;
271
272
 
272
273
  Unknown keys are refused. Retired keys are refused with what to do instead (`RETIRED_CHANNEL_KEYS`): `raw`, `is_primary`, the listing-style parameter trio, `grants`, `rate_limits` (nothing reads it; use `rate_limit_refs`), `storage_type` (use `access_method: s3`), `response_rules`, `timeout_ms`, `transport`, and the platform-derived `customer_secrets_required` / `customer_secrets_optional`.
273
274
 
275
+ ### External apps and product links
276
+
277
+ An offering that declares no channel (`upstream_access_config` omitted or `{}`) is an **external app**: customers reach it at its own site, not through the gateway (unitysvc/unitysvc#2873). `external` is not a channel type. An external app:
278
+
279
+ - gives its homepage in `details.links.homepage` (required; the provider's homepage is not substituted);
280
+ - has no `user_access_interfaces` and no `list_price` (signup and payment happen at its site);
281
+ - needs no connectivity-test document.
282
+
283
+ `details.links` holds an offering's product links, for any service: up to 10 free display labels (at most 40 characters each) mapped to `https://` URLs without embedded credentials. When present it must include `homepage`, the primary product link. The rest of `details` stays free-form. `validate_details_links` checks it on every `offering_v1`.
284
+
285
+ ```json
286
+ {
287
+ "details": {
288
+ "links": {
289
+ "homepage": "https://app.example",
290
+ "documentation": "https://app.example/docs"
291
+ }
292
+ }
293
+ }
294
+ ```
295
+
274
296
  ### Enrollment parameters on channels
275
297
 
276
298
  A channel declares the enrollment parameters it reads, so each plan of a service asks for what it needs (unitysvc/unitysvc#2726). A listing declares none: `user_parameters_schema`, `user_parameters_ui_schema` and `service_options.ops_testing_parameters` are refused.
@@ -173,12 +173,13 @@ Three stages (unitysvc/unitysvc#2720): a target service's **`exports`** (what it
173
173
  "limits": {"count_per_day": 1000}}]
174
174
  ```
175
175
 
176
- - `object` names one service (`service:<name>`, no wildcards), or `apikey` for the leased key's lifespan (below). `permissions` are plain names (lowercase letters, digits and `_`; no wildcards), checked against the target's exports with a catalog.
176
+ - `object` names one service (`service:<name>`, no wildcards), a resource the platform provisions for the enrollment (`resource:room`, below), or `apikey` for the leased key's lifespan (below). `permissions` are plain names (lowercase letters, digits and `_`; no wildcards), checked against the target's exports with a catalog.
177
177
  - `required` (`true` or `false`, on every entry, `apikey` included) says whether the customer may decline the request. A stored declaration from before this rule reads as optional when a policy is built.
178
178
  - `options` is written in query-string syntax (`parse_options`; a notation, not how options are delivered): each name once, each value non-empty; with a catalog, each value is converted to its declared type and validated against the target's `options` schema.
179
179
  - **A request's `options` are fixed.** Every option it declares is in the policy of an approved request, with the declared value; the customer may repeat it but not change or drop it. An option the request does not declare is the customer's to set at enrollment (a form rendered from the target's `options` schema). So `{"object": "service:ai", ...}` lets the customer pick the AI service, and `"options": "service=labs/llm-balanced"` pins it.
180
180
  - Several requests may name one object (two kinds of room) only if each fixes some option to a different value (`kind=chat`, `kind=feed`), so an approval says which one it is.
181
181
  - `limits` (`validate_limits`): `count_per_hour` / `count_per_day` / `count_per_month` / `count_total` (positive integer) and the same for `amount_` (finite positive decimal, as a number or a string). Limits are universal: the platform meters every call, so any service can be limited without exporting anything. The seller's limits only pre-fill the form; the customer sets them at enrollment, and an enrollment's own limits (unitysvc/unitysvc#2687) use the same shape. They are counted per policy entry (the enrollment's calls to that service) from the usage stream (counters keyed by scope, metric and window bucket), and the gateway refuses calls once one is exceeded.
182
+ - **A room the platform provisions** (unitysvc/unitysvc#2830) is asked for with `resource:room`: `{"object": "resource:room", "permissions": ["create"], "required": true, "justification": "Creates your chat room", "options": "kind=chat&max_members=100"}`. Core knows the resource, so no catalog is consulted. The request must fix `kind`, the room's identity; each kind bounds the permissions (`chat`: `create`, a room the customer owns; `support`: `join`, `read`, `post`, the seller's private room with the customer; `announcement`: `join`, `read`; `discussion`: `join`, `read`, `post`). `max_members` (a positive integer) caps only a room the customer creates. A channel requests each kind at most once, and a resource takes no limits.
182
183
  - **A longer-lived leased key** is asked for with one `apikey` entry: `{"object": "apikey", "required": false, "limits": {"api_key_lifespan": 14400}, "justification": "Batch runs take up to four hours"}`. It names the key itself, so it takes only `limits` (exactly `api_key_lifespan`, whole seconds from 1 to 86400), `required` and a `justification`, needs no catalog lookup, and grants nothing. Without it, a key the seller leases for the enrollment lives `DEFAULT_API_KEY_LIFESPAN` (3600 s). `api_key_lifespan` is valid only on this entry.
183
184
 
184
185
  **3. How options reach the service.** Not through the upstream URL: the gateway never changes a target's `base_url` or query to carry policy. How an option is applied is up to the service's implementation:
@@ -224,7 +225,7 @@ A policy has three kinds of entry (unitysvc/unitysvc#2770):
224
225
  | Channel key | What it is |
225
226
  | --- | --- |
226
227
  | `access_method` | `http` (default), `smtp`, `s3` or `mcp`; selects the server type |
227
- | `type` | normally derived by the platform; declare `external` (or `enrollable`) to state it |
228
+ | `type` | normally derived by the platform; declare `enrollable` to state it |
228
229
  | `description`, `is_active`, `sort_order` | display text; inactive channels are skipped; rank, lowest first |
229
230
  | `request_formats`, `applicable_interfaces` | the formats the channel serves; the interfaces that reach it (display only) |
230
231
  | `rate_limit_refs` | the provider rate limits it consumes |
@@ -236,6 +237,27 @@ The common one-server case writes the connection fields directly on the channel;
236
237
 
237
238
  Unknown keys are refused. Retired keys are refused with what to do instead (`RETIRED_CHANNEL_KEYS`): `raw`, `is_primary`, the listing-style parameter trio, `grants`, `rate_limits` (nothing reads it; use `rate_limit_refs`), `storage_type` (use `access_method: s3`), `response_rules`, `timeout_ms`, `transport`, and the platform-derived `customer_secrets_required` / `customer_secrets_optional`.
238
239
 
240
+ ### External apps and product links
241
+
242
+ An offering that declares no channel (`upstream_access_config` omitted or `{}`) is an **external app**: customers reach it at its own site, not through the gateway (unitysvc/unitysvc#2873). `external` is not a channel type. An external app:
243
+
244
+ - gives its homepage in `details.links.homepage` (required; the provider's homepage is not substituted);
245
+ - has no `user_access_interfaces` and no `list_price` (signup and payment happen at its site);
246
+ - needs no connectivity-test document.
247
+
248
+ `details.links` holds an offering's product links, for any service: up to 10 free display labels (at most 40 characters each) mapped to `https://` URLs without embedded credentials. When present it must include `homepage`, the primary product link. The rest of `details` stays free-form. `validate_details_links` checks it on every `offering_v1`.
249
+
250
+ ```json
251
+ {
252
+ "details": {
253
+ "links": {
254
+ "homepage": "https://app.example",
255
+ "documentation": "https://app.example/docs"
256
+ }
257
+ }
258
+ }
259
+ ```
260
+
239
261
  ### Enrollment parameters on channels
240
262
 
241
263
  A channel declares the enrollment parameters it reads, so each plan of a service asks for what it needs (unitysvc/unitysvc#2726). A listing declares none: `user_parameters_schema`, `user_parameters_ui_schema` and `service_options.ops_testing_parameters` are refused.
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "unitysvc-core"
7
- version = "0.3.3"
7
+ version = "0.3.5"
8
8
  description = "Shared data models and validation helpers for UnitySVC packages"
9
9
  readme = "README.md"
10
10
  authors = [{ name = "Bo Peng", email = "bo.peng@unitysvc.com" }]
@@ -78,10 +78,14 @@ customer consent and key issuance establish its *authority*.
78
78
  be limited by ``count`` or ``amount`` per hour, day or month, or in total,
79
79
  without exporting anything (``{"count_per_day": 2, "amount_per_month": "2.00"}``).
80
80
 
81
- Today a request's ``object`` is ``service:<name>``, or ``apikey``: how long a
82
- key leased for the enrollment lives (``limits.api_key_lifespan``, up to a day,
83
- with a justification), which grants nothing. :func:`build_policy` turns a
84
- customer's approvals into the policy an enrollment keeps.
81
+ A request's ``object`` is ``service:<name>``; or ``resource:room``, a room the
82
+ platform provisions for the enrollment (unitysvc/unitysvc#2830), whose
83
+ ``kind`` (``chat``, ``support``, ``announcement``, ``discussion``) the
84
+ request fixes and whose permissions the kind bounds (:data:`ROOM_KINDS`); or
85
+ ``apikey``: how long a key leased for the enrollment lives
86
+ (``limits.api_key_lifespan``, up to a day, with a justification), which grants
87
+ nothing. :func:`build_policy` turns a customer's approvals into the policy an
88
+ enrollment keeps.
85
89
 
86
90
  A policy has three kinds of entry (unitysvc/unitysvc#2770):
87
91
 
@@ -179,6 +183,36 @@ ALL_ROUTES = "* /*"
179
183
  DEFAULT_PERMISSIONS: dict[str, tuple[str, ...]] = {INVOKE: (ALL_ROUTES,)}
180
184
  DEFAULT_EXPORTS = Exports(DEFAULT_PERMISSIONS, {})
181
185
 
186
+ # What a request may ask the platform to provision for the enrolling customer,
187
+ # rather than a service to call (unitysvc/unitysvc#2830): ``resource:<name>``.
188
+ # Core knows each resource, so its claims need no catalog lookup.
189
+ RESOURCE_PREFIX = "resource:"
190
+ # A room's kind is its identity: a request fixes it, and each kind allows the
191
+ # permissions its provisioning grants. The customer creates and owns a chat
192
+ # room; the others are the seller's rooms the customer is admitted to (a
193
+ # private support room, a read-only announcement room, a discussion room).
194
+ ROOM_KINDS: dict[str, frozenset[str]] = {
195
+ "chat": frozenset({"create"}),
196
+ "support": frozenset({"join", "read", "post"}),
197
+ "announcement": frozenset({"join", "read"}),
198
+ "discussion": frozenset({"join", "read", "post"}),
199
+ }
200
+ ROOM_KIND = "kind"
201
+ ROOM_MAX_MEMBERS = "max_members"
202
+ RESOURCES: dict[str, Exports] = {
203
+ "room": Exports(
204
+ {name: () for name in ("create", "join", "read", "post")},
205
+ {
206
+ "type": "object",
207
+ "additionalProperties": False,
208
+ "properties": {
209
+ ROOM_KIND: {"type": "string", "enum": list(ROOM_KINDS)},
210
+ ROOM_MAX_MEMBERS: {"type": "integer", "minimum": 1},
211
+ },
212
+ },
213
+ ),
214
+ }
215
+
182
216
  _REQUEST_KEYS = frozenset({"object", "permissions", "required", "justification", "options", "limits"})
183
217
  _APIKEY_REQUEST_KEYS = frozenset({"object", "required", "justification", "limits"})
184
218
  # What a policy entry (an approved request) holds.
@@ -425,13 +459,24 @@ def validate_access_requests(
425
459
  continue
426
460
  if obj == SERVICE_WILDCARD:
427
461
  raise ValueError(_service_wildcard_refusal(at, "requested"))
428
- if not obj.startswith(SERVICE_PREFIX):
429
- raise ValueError(f"{at}: {obj!r} cannot be requested; name one service as 'service:<name>'")
430
- name = obj.removeprefix(SERVICE_PREFIX)
431
- try:
432
- validate_service_identifier(name, "requested service")
433
- except ValueError as exc:
434
- raise ValueError(f"{at}: {obj!r} cannot be requested: {exc}") from None
462
+ resource = obj.startswith(RESOURCE_PREFIX)
463
+ name = obj.removeprefix(RESOURCE_PREFIX if resource else SERVICE_PREFIX)
464
+ if resource:
465
+ if name not in RESOURCES:
466
+ raise ValueError(
467
+ f"{at}: {obj!r} cannot be requested; the resources are "
468
+ + ", ".join(f"'{RESOURCE_PREFIX}{r}'" for r in RESOURCES)
469
+ )
470
+ elif not obj.startswith(SERVICE_PREFIX):
471
+ raise ValueError(
472
+ f"{at}: {obj!r} cannot be requested; name one service as 'service:<name>' "
473
+ f"or a resource as '{RESOURCE_PREFIX}<name>'"
474
+ )
475
+ else:
476
+ try:
477
+ validate_service_identifier(name, "requested service")
478
+ except ValueError as exc:
479
+ raise ValueError(f"{at}: {obj!r} cannot be requested: {exc}") from None
435
480
  if extra := set(entry) - _REQUEST_KEYS:
436
481
  raise ValueError(f"{at}: unknown keys {sorted(extra)}")
437
482
  justification = entry.get("justification")
@@ -449,7 +494,14 @@ def validate_access_requests(
449
494
  options = parse_options(f"{at}.options", entry.get("options", ""))
450
495
  validate_limits(f"{at}.limits", entry.get("limits", {}))
451
496
  exports = None
452
- if resolve is not None:
497
+ if resource:
498
+ exports = RESOURCES[name]
499
+ check_resource(at, obj, permissions, options, entry.get("limits"))
500
+ if kind := next(
501
+ (o[ROOM_KIND] for other, o, _ in seen if other == obj and o[ROOM_KIND] == options[ROOM_KIND]), None
502
+ ):
503
+ raise ValueError(f"{at}: {obj} with {ROOM_KIND}={kind} is listed twice; a kind is requested once")
504
+ elif resolve is not None:
453
505
  declared = resolve(name)
454
506
  if declared is None:
455
507
  raise ValueError(f"{at}: {obj} is not a published service")
@@ -560,6 +612,29 @@ def check_claim(where: str, obj: str, permissions: list[str], options: dict[str,
560
612
  raise ValueError(f"{where}.options: {error}")
561
613
 
562
614
 
615
+ def check_resource(where: str, obj: str, permissions: list[str], options: dict[str, str], limits: Any = None) -> None:
616
+ """Refuse a claim on ``obj`` (``resource:<name>``) that the resource does
617
+ not allow, for a request and for a policy entry alike.
618
+
619
+ A room claim names its ``kind`` in its options; its permissions are some
620
+ of those the kind allows, and ``max_members`` (a positive integer) only
621
+ caps a room the customer creates. A resource is provisioned, not called,
622
+ so it takes no limits.
623
+ """
624
+ check_claim(where, obj, permissions, options, RESOURCES[obj.removeprefix(RESOURCE_PREFIX)])
625
+ if limits:
626
+ raise ValueError(f"{where}.limits: {obj} is provisioned, not called; it takes no limits")
627
+ kind = options.get(ROOM_KIND)
628
+ if kind is None:
629
+ raise ValueError(
630
+ f"{where}.options must set {ROOM_KIND} (one of {list(ROOM_KINDS)}): a room's kind is its identity"
631
+ )
632
+ if not set(permissions) <= ROOM_KINDS[kind]:
633
+ raise ValueError(f"{where}.permissions: a {kind} room allows only {sorted(ROOM_KINDS[kind])}")
634
+ if ROOM_MAX_MEMBERS in options and "create" not in ROOM_KINDS[kind]:
635
+ raise ValueError(f"{where}.options.{ROOM_MAX_MEMBERS}: only a room the customer creates takes a member cap")
636
+
637
+
563
638
  def validate_channel_access_requests(config: Any, resolve: ExportsResolver | None = None) -> None:
564
639
  """Refuse the ``customer_access_requests`` of any channel of an ``upstream_access_config``
565
640
  unless valid. Each channel declares its own (unitysvc/unitysvc#2726)."""
@@ -619,7 +694,10 @@ def build_policy(requests: Any, approvals: Any, resolve: ExportsResolver | None
619
694
  elif extra := set(approval) - _POLICY_KEYS - {ENROLLMENT_KEY}:
620
695
  raise ValueError(f"{at}: unknown keys {sorted(extra)}")
621
696
  exports = None
622
- if resolve is not None and obj.startswith(SERVICE_PREFIX) and any(r["object"] == obj for r in requests):
697
+ resource = obj.startswith(RESOURCE_PREFIX) and obj.removeprefix(RESOURCE_PREFIX) in RESOURCES
698
+ if resource:
699
+ exports = RESOURCES[obj.removeprefix(RESOURCE_PREFIX)]
700
+ elif resolve is not None and obj.startswith(SERVICE_PREFIX) and any(r["object"] == obj for r in requests):
623
701
  declared = resolve(obj.removeprefix(SERVICE_PREFIX))
624
702
  if declared is None:
625
703
  raise ValueError(f"{at}: {obj} is not a published service")
@@ -655,7 +733,9 @@ def build_policy(requests: Any, approvals: Any, resolve: ExportsResolver | None
655
733
  options = {**parse_options(f"{at}.options", approval.get("options", "")), **fixed}
656
734
  limits = approval.get("limits", {})
657
735
  validate_limits(f"{at}.limits", limits)
658
- if exports is not None:
736
+ if resource:
737
+ check_resource(at, obj, permissions, options, limits)
738
+ elif exports is not None:
659
739
  check_claim(at, obj, permissions, options, exports)
660
740
  entry: dict[str, Any] = {"object": obj, "permissions": list(permissions)}
661
741
  if code is not None:
@@ -291,6 +291,9 @@ class RequestTransformEnum(StrEnum):
291
291
  class ServiceTypeEnum(StrEnum):
292
292
  """Broad service category — defines the access pattern and protocol.
293
293
 
294
+ Optional on an offering: a service that fits none leaves it out, and
295
+ describes what it does with capabilities and tags.
296
+
294
297
  AI modalities (vision, tools, rerank, etc.) are tracked via the
295
298
  `capabilities` list on ServiceOffering, not service_type.
296
299
  """
@@ -334,6 +337,12 @@ class ServiceTypeEnum(StrEnum):
334
337
  monitoring = "monitoring" # Uptime checks, health monitoring
335
338
  analytics = "analytics" # Recommendation, anomaly detection, forecasting
336
339
 
340
+ # === Applications ===
341
+ # Two-way or many-way exchanges between the customer and others, rather
342
+ # than answering calls; having an endpoint or not is not what makes one.
343
+ communication = "communication" # Conversations among several parties (Commons rooms, unitysvc/unitysvc#2823)
344
+ buy_and_sell = "buy_and_sell" # Buyers and sellers dealing with each other (AIMM)
345
+
337
346
 
338
347
  class ServiceVisibilityEnum(StrEnum):
339
348
  """Visibility of a service in the catalog.
@@ -165,7 +165,9 @@ class McpServer(_Server):
165
165
  allowed_hosts: list[str] | None = None
166
166
 
167
167
 
168
- ChannelType = Literal["unbound", "secret_bound", "enrollable", "me_bound", "external"]
168
+ # Derived by the platform. An app with no channel at all (an external app,
169
+ # unitysvc/unitysvc#2873) is not a channel type: it declares no channel.
170
+ ChannelType = Literal["unbound", "secret_bound", "enrollable", "me_bound"]
169
171
 
170
172
  # Keys a channel no longer takes, with what to do instead.
171
173
  RETIRED_CHANNEL_KEYS: dict[str, str] = {
@@ -193,7 +195,7 @@ class _ChannelBase(BaseModel):
193
195
 
194
196
  type: ChannelType | None = Field(
195
197
  default=None,
196
- description="Normally derived by the platform; declare 'external' (or 'enrollable') to state it",
198
+ description="Normally derived by the platform; declare 'enrollable' to state it",
197
199
  )
198
200
  description: str | None = None
199
201
  is_active: bool = True
@@ -53,9 +53,12 @@ class ServiceOfferingData(BaseModel):
53
53
  description="Human-readable service name for display (e.g., 'GPT-4 Turbo', 'Claude 3 Opus')",
54
54
  )
55
55
 
56
- service_type: ServiceTypeEnum = Field(
57
- default=ServiceTypeEnum.llm,
58
- description="Category for grouping/comparison",
56
+ service_type: ServiceTypeEnum | None = Field(
57
+ default=None,
58
+ description=(
59
+ "Category for grouping/comparison; omit it when none fits, and describe the service "
60
+ "with capabilities and tags"
61
+ ),
59
62
  )
60
63
 
61
64
  capabilities: list[str] = Field(
@@ -1,13 +1,13 @@
1
1
  from datetime import datetime
2
2
  from typing import Any
3
3
 
4
- from pydantic import ConfigDict, Field, HttpUrl, field_validator
4
+ from pydantic import ConfigDict, Field, HttpUrl, field_validator, model_validator
5
5
 
6
6
  from .channel import UpstreamAccessConfig
7
7
  from .documents import DocumentData
8
8
  from .offering_data import ServiceOfferingData
9
9
  from .pricing import Pricing
10
- from .validators import validate_service_identifier
10
+ from .validators import validate_details_links, validate_service_identifier
11
11
 
12
12
 
13
13
  class OfferingV1(ServiceOfferingData):
@@ -33,16 +33,22 @@ class OfferingV1(ServiceOfferingData):
33
33
  # Static information (optional — not all service types have meaningful details)
34
34
  details: dict[str, Any] = Field( # type: ignore[assignment]
35
35
  default_factory=dict,
36
- description="Dictionary of static features and information",
36
+ description=(
37
+ "Dictionary of static features and information. Its 'links' key holds the product "
38
+ "links (label -> https:// URL, including 'homepage'), required when the offering "
39
+ "declares no channel"
40
+ ),
37
41
  )
38
42
 
39
43
  # Convenience field for logo (converted to documents during import)
40
44
  logo: str | HttpUrl | None = None
41
45
 
42
- # Required in file validation (the base allows None and keeps channels as
43
- # plain dicts, for stored data the platform has annotated).
46
+ # The base allows None and keeps channels as plain dicts, for stored data
47
+ # the platform has annotated. Omitted and empty are the same: an offering
48
+ # with no channel, an external app reached at its own site (#2873).
44
49
  upstream_access_config: UpstreamAccessConfig = Field( # type: ignore[assignment]
45
- description="Upstream access channels, keyed by channel name",
50
+ default_factory=lambda: UpstreamAccessConfig({}),
51
+ description="Upstream access channels, keyed by channel name; omit for an external app",
46
52
  )
47
53
 
48
54
  documents: dict[str, DocumentData] | None = Field( # type: ignore[assignment]
@@ -55,6 +61,15 @@ class OfferingV1(ServiceOfferingData):
55
61
  description="Payout pricing: How to calculate seller payout",
56
62
  )
57
63
 
64
+ @model_validator(mode="after")
65
+ def _validate_links(self) -> "OfferingV1":
66
+ """Product links are well formed, and an offering with no channel has
67
+ its homepage (unitysvc/unitysvc#2873)."""
68
+ channel_less = not self.upstream_access_config.root
69
+ if errors := validate_details_links(self.details, channel_less=channel_less):
70
+ raise ValueError("; ".join(errors))
71
+ return self
72
+
58
73
  @field_validator("name")
59
74
  @classmethod
60
75
  def validate_name_format(cls, v: str) -> str:
@@ -915,11 +915,11 @@ def validate_mcp_offering(data: dict[str, Any] | None) -> list[str]:
915
915
  if mcp_channels:
916
916
  declarations.append("MCP upstream channel(s) " + ", ".join(repr(name) for name in mcp_channels))
917
917
  if declarations:
918
- return [
919
- f"service_type {service_type!r} may not declare "
920
- + "; ".join(declarations)
921
- + "; use service_type 'mcp' instead"
922
- ]
918
+ # service_type is optional (unitysvc/unitysvc#2833): name what is there.
919
+ declared = (
920
+ f"service_type {service_type!r}" if service_type is not None else "an offering without service_type"
921
+ )
922
+ return [f"{declared} may not declare " + "; ".join(declarations) + "; use service_type 'mcp' instead"]
923
923
  return []
924
924
 
925
925
  if not channels or not isinstance(channels, dict):
@@ -1297,3 +1297,69 @@ def validate_listing_jinja_var_references(data: dict[str, Any] | None) -> list[s
1297
1297
  errors.append(f"{field_path}: Jinja syntax error in '{value}' — {exc.message}.")
1298
1298
 
1299
1299
  return errors
1300
+
1301
+
1302
+ HOMEPAGE_LINK = "homepage"
1303
+ MAX_LINKS = 10
1304
+ MAX_LINK_LABEL_LENGTH = 40
1305
+
1306
+
1307
+ def validate_details_links(details: dict[str, Any] | None, *, channel_less: bool) -> list[str]:
1308
+ """Check an offering's product links, ``details.links`` (unitysvc/unitysvc#2873).
1309
+
1310
+ Product links (homepage, documentation, support, …) describe the product,
1311
+ whether or not it is delivered through the gateway, and are kept apart from
1312
+ the operational ``upstream_access_config``. When present, ``details.links``
1313
+ maps up to ``MAX_LINKS`` nonempty display labels (at most
1314
+ ``MAX_LINK_LABEL_LENGTH`` characters) to ``https://`` URLs without embedded
1315
+ credentials, and includes ``homepage``, the primary product link; the rest
1316
+ of ``details`` stays free-form. An offering with no channel (an app reached
1317
+ at its own site) must provide it: its homepage is how customers reach it.
1318
+ """
1319
+ from pydantic import HttpUrl, TypeAdapter, ValidationError
1320
+
1321
+ url_adapter = TypeAdapter(HttpUrl)
1322
+ links = (details or {}).get("links")
1323
+ if links is None:
1324
+ if channel_less:
1325
+ return [
1326
+ "An offering with no upstream_access_config channel is an external app: "
1327
+ f"details.links.{HOMEPAGE_LINK} must give its https:// homepage"
1328
+ ]
1329
+ return []
1330
+ if not isinstance(links, dict):
1331
+ return ["details.links must be an object of link label -> https:// URL"]
1332
+ errors: list[str] = []
1333
+ if len(links) > MAX_LINKS:
1334
+ errors.append(f"details.links may hold at most {MAX_LINKS} links, got {len(links)}")
1335
+ for label, url in links.items():
1336
+ where = f"details.links.{label}"
1337
+ if not isinstance(label, str) or not label.strip():
1338
+ errors.append("details.links: a link label must be a nonempty string")
1339
+ continue
1340
+ if len(label) > MAX_LINK_LABEL_LENGTH:
1341
+ errors.append(f"details.links: the label {label!r} is longer than {MAX_LINK_LABEL_LENGTH} characters")
1342
+ if not isinstance(url, str) or not url.strip():
1343
+ errors.append(f"{where} must be a nonempty https:// URL")
1344
+ continue
1345
+ # HttpUrl repairs some malformed input (``https:app.example`` becomes
1346
+ # ``https://app.example/``), but the original string is what is stored
1347
+ # and rendered as an href, where it would resolve relative to the
1348
+ # page. So the string itself must be an absolute ``https://`` URL with
1349
+ # an authority; HttpUrl then checks the host, port and the rest.
1350
+ authority = url[len("https://") :]
1351
+ if url != url.strip() or not url.lower().startswith("https://") or authority[:1] in ("", "/", "\\"):
1352
+ errors.append(f"{where} must be an https:// URL, got {url!r}")
1353
+ continue
1354
+ try:
1355
+ parsed = url_adapter.validate_python(url)
1356
+ except (ValidationError, ValueError):
1357
+ errors.append(f"{where} must be an https:// URL, got {url!r}")
1358
+ continue
1359
+ if parsed.scheme != "https" or not parsed.host:
1360
+ errors.append(f"{where} must be an https:// URL, got {url!r}")
1361
+ elif parsed.username is not None or parsed.password is not None:
1362
+ errors.append(f"{where} must not embed credentials")
1363
+ if HOMEPAGE_LINK not in links:
1364
+ errors.append(f"details.links must include '{HOMEPAGE_LINK}', the primary product link")
1365
+ return errors
@@ -1242,8 +1242,7 @@
1242
1242
  "unbound",
1243
1243
  "secret_bound",
1244
1244
  "enrollable",
1245
- "me_bound",
1246
- "external"
1245
+ "me_bound"
1247
1246
  ],
1248
1247
  "type": "string"
1249
1248
  },
@@ -1252,7 +1251,7 @@
1252
1251
  }
1253
1252
  ],
1254
1253
  "default": null,
1255
- "description": "Normally derived by the platform; declare 'external' (or 'enrollable') to state it",
1254
+ "description": "Normally derived by the platform; declare 'enrollable' to state it",
1256
1255
  "title": "Type"
1257
1256
  },
1258
1257
  "upstream_format": {
@@ -1993,8 +1992,7 @@
1993
1992
  "unbound",
1994
1993
  "secret_bound",
1995
1994
  "enrollable",
1996
- "me_bound",
1997
- "external"
1995
+ "me_bound"
1998
1996
  ],
1999
1997
  "type": "string"
2000
1998
  },
@@ -2003,7 +2001,7 @@
2003
2001
  }
2004
2002
  ],
2005
2003
  "default": null,
2006
- "description": "Normally derived by the platform; declare 'external' (or 'enrollable') to state it",
2004
+ "description": "Normally derived by the platform; declare 'enrollable' to state it",
2007
2005
  "title": "Type"
2008
2006
  },
2009
2007
  "weight": {
@@ -2750,8 +2748,7 @@
2750
2748
  "unbound",
2751
2749
  "secret_bound",
2752
2750
  "enrollable",
2753
- "me_bound",
2754
- "external"
2751
+ "me_bound"
2755
2752
  ],
2756
2753
  "type": "string"
2757
2754
  },
@@ -2760,7 +2757,7 @@
2760
2757
  }
2761
2758
  ],
2762
2759
  "default": null,
2763
- "description": "Normally derived by the platform; declare 'external' (or 'enrollable') to state it",
2760
+ "description": "Normally derived by the platform; declare 'enrollable' to state it",
2764
2761
  "title": "Type"
2765
2762
  },
2766
2763
  "weight": {
@@ -2946,7 +2943,7 @@
2946
2943
  "type": "object"
2947
2944
  },
2948
2945
  "ServiceTypeEnum": {
2949
- "description": "Broad service category — defines the access pattern and protocol.\n\nAI modalities (vision, tools, rerank, etc.) are tracked via the\n`capabilities` list on ServiceOffering, not service_type.",
2946
+ "description": "Broad service category — defines the access pattern and protocol.\n\nOptional on an offering: a service that fits none leaves it out, and\ndescribes what it does with capabilities and tags.\n\nAI modalities (vision, tools, rerank, etc.) are tracked via the\n`capabilities` list on ServiceOffering, not service_type.",
2950
2947
  "enum": [
2951
2948
  "llm",
2952
2949
  "embedding",
@@ -2961,7 +2958,9 @@
2961
2958
  "mcp",
2962
2959
  "database",
2963
2960
  "monitoring",
2964
- "analytics"
2961
+ "analytics",
2962
+ "communication",
2963
+ "buy_and_sell"
2965
2964
  ],
2966
2965
  "title": "ServiceTypeEnum",
2967
2966
  "type": "string"
@@ -3182,8 +3181,7 @@
3182
3181
  "unbound",
3183
3182
  "secret_bound",
3184
3183
  "enrollable",
3185
- "me_bound",
3186
- "external"
3184
+ "me_bound"
3187
3185
  ],
3188
3186
  "type": "string"
3189
3187
  },
@@ -3192,7 +3190,7 @@
3192
3190
  }
3193
3191
  ],
3194
3192
  "default": null,
3195
- "description": "Normally derived by the platform; declare 'external' (or 'enrollable') to state it",
3193
+ "description": "Normally derived by the platform; declare 'enrollable' to state it",
3196
3194
  "title": "Type"
3197
3195
  },
3198
3196
  "username": {
@@ -3665,7 +3663,7 @@
3665
3663
  },
3666
3664
  "details": {
3667
3665
  "additionalProperties": true,
3668
- "description": "Dictionary of static features and information",
3666
+ "description": "Dictionary of static features and information. Its 'links' key holds the product links (label -> https:// URL, including 'homepage'), required when the offering declares no channel",
3669
3667
  "title": "Details",
3670
3668
  "type": "object"
3671
3669
  },
@@ -3841,9 +3839,16 @@
3841
3839
  "title": "Payout Price"
3842
3840
  },
3843
3841
  "service_type": {
3844
- "$ref": "#/$defs/ServiceTypeEnum",
3845
- "default": "llm",
3846
- "description": "Category for grouping/comparison"
3842
+ "anyOf": [
3843
+ {
3844
+ "$ref": "#/$defs/ServiceTypeEnum"
3845
+ },
3846
+ {
3847
+ "type": "null"
3848
+ }
3849
+ ],
3850
+ "default": null,
3851
+ "description": "Category for grouping/comparison; omit it when none fits, and describe the service with capabilities and tags"
3847
3852
  },
3848
3853
  "status": {
3849
3854
  "$ref": "#/$defs/OfferingStatusEnum",
@@ -3879,14 +3884,13 @@
3879
3884
  },
3880
3885
  "upstream_access_config": {
3881
3886
  "$ref": "#/$defs/UpstreamAccessConfig",
3882
- "description": "Upstream access channels, keyed by channel name"
3887
+ "description": "Upstream access channels, keyed by channel name; omit for an external app"
3883
3888
  }
3884
3889
  },
3885
3890
  "required": [
3886
3891
  "name",
3887
3892
  "summary",
3888
3893
  "description",
3889
- "upstream_access_config",
3890
3894
  "time_created"
3891
3895
  ],
3892
3896
  "title": "OfferingV1",