@interop/was-client 0.99.1 → 0.100.1

package/dist/internal/paths.d.ts

@@ -1,307 +1,535 @@
 /**
- * `/space/:spaceId/` -- the Space container in canonical form: the target a
- * Space root capability names, the URL whose `GET` lists the Space's
- * Collections, whose `POST` creates one, and whose `DELETE` removes the Space.
- * The Space is an ordinary container, so its members are listed and created at
- * the container itself -- there is no second builder for that.
+ * Parses an absolute `http(s)` URL, or returns `null`. The one rule for which
+ * URLs may name a server, a Spaces Repository, or a container here; the
+ * callers that need more (no query, a path) narrow it.
  *
- * @param spaceId {string}
+ * @param url {string}
+ * @returns {URL | null}
+ */
+export declare function parseAbsoluteHttpUrl(url: string): URL | null;
+/**
+ * Whether a canonical container URL is an origin root (`https://h/`).
+ *
+ * @param canonical {string}
+ * @returns {boolean}
+ */
+export declare function isOriginRoot(canonical: string): boolean;
+/**
+ * The base server URL in canonical form: the URL under which a server lays
+ * out `service`, `spaces/` and `space/{space_id}/`. An absolute `http(s)` URL
+ * with no query or fragment; a missing trailing slash is supplied rather than
+ * refused, since `https://h/pws` and `https://h/pws/` can only mean the same
+ * mount.
+ *
+ * @param baseServerUrl {string}
+ * @returns {string}
+ * @throws {ValidationError}   when the value is not an absolute `http(s)` URL,
+ *   or carries a query or fragment
+ */
+export declare function canonicalBaseServerUrl(baseServerUrl: string): string;
+/**
+ * `{base}service` -- the service description of the server at
+ * `baseServerUrl`.
+ *
+ * @param options {object}
+ * @param options.baseServerUrl {string}
+ * @returns {string}
+ */
+export declare function serviceDescriptionUrl({ baseServerUrl }: {
+    baseServerUrl: string;
+}): string;
+/**
+ * `{base}spaces/` -- the Spaces Repository of the server at `baseServerUrl`,
+ * in canonical container form. The server may not implement one; its service
+ * description says.
+ *
+ * @param options {object}
+ * @param options.baseServerUrl {string}
+ * @returns {string}
+ */
+export declare function spacesRepositoryUrl({ baseServerUrl }: {
+    baseServerUrl: string;
+}): string;
+/**
+ * `{base}space/{space_id}/` -- the Space with id `spaceId` on the server at
+ * `baseServerUrl`, in canonical form. The one place a Space URL is built
+ * rather than received; the spec's Server Layout fixes this shape.
+ *
+ * @param options {object}
+ * @param options.baseServerUrl {string}
+ * @param options.spaceId {string}
  * @returns {string}
+ * @throws {ValidationError}   when `spaceId` is empty or a dot segment
  */
-export declare function spacePath(spaceId: string): string;
+export declare function spaceUrlById({ baseServerUrl, spaceId }: {
+    baseServerUrl: string;
+    spaceId: string;
+}): string;
 /**
- * `/space/:spaceId/meta` -- the Space Metadata object: the Space's description
+ * The base server URL a server-level URL sits under: the inverse of
+ * {@link serviceDescriptionUrl}, {@link spacesRepositoryUrl} and
+ * {@link spaceUrlById}. Accepts the service description URL (`{base}service`),
+ * the Spaces Repository URL (`{base}spaces/`, slash optional) or a Space URL
+ * (`{base}space/{space_id}/`, slash optional) and strips exactly the segments
+ * the layout adds. Anything else is refused, including a Collection or
+ * Resource URL, whose depth cannot be told from the string alone, and the
+ * URL of a single fixed Space, which has no base server URL.
+ *
+ * @param url {string}
+ * @returns {string}
+ * @throws {ValidationError}   when `url` is not an absolute `http(s)` URL
+ *   without query or fragment in one of the three forms
+ */
+export declare function baseServerUrlOf(url: string): string;
+/**
+ * Splits an absolute Collection URL into the Space URL it sits under and the
+ * Collection id: the parent container and the last segment, percent-decoded.
+ * A Collection URL is always the Space URL plus one segment, so no layout
+ * knowledge is needed. The bare form (no trailing slash) is accepted, as for
+ * any container URL received from outside.
+ *
+ * @param collectionUrl {string}
+ * @returns {{ spaceUrl: string; collectionId: string }}
+ * @throws {ValidationError}   when `collectionUrl` is not an absolute `http(s)`
+ *   URL without query or fragment, has no path segment, or its last segment
+ *   is a malformed percent escape
+ */
+export declare function splitCollectionUrl(collectionUrl: string): {
+    spaceUrl: string;
+    collectionId: string;
+};
+/**
+ * The Space URL in canonical form (see `canonicalContainer`). A server names
+ * a Space in this form (the `Location` of the create response, a listing
+ * item's `url`), and every URL beneath the Space, and every zcap
+ * `invocationTarget`, is derived from it, so a caller's own serialization of
+ * the same Space must reduce to the same string. An origin root is a valid
+ * Space URL: a single fixed Space (one with no Space id and no base server
+ * URL) may be served there.
+ *
+ * @param spaceUrl {string}   a Space URL, as the server named it or as the
+ *   caller stored it
+ * @returns {string}
+ * @throws {ValidationError}   when `spaceUrl` is not an absolute `http(s)`
+ *   URL, carries a query or fragment, or has an empty path segment
+ */
+export declare function canonicalSpaceUrl(spaceUrl: string): string;
+/**
+ * The Space's id as its URL names it: the last path segment of the Space
+ * URL, percent-decoded. The spec's hierarchy and its did:webvh profile both
+ * place the id there (`.../space/{space_id}/`), and it is the value the Space
+ * Metadata object's `id` carries. A single fixed Space at an origin root has
+ * no id, so that URL is refused here.
+ *
+ * @param spaceUrl {string}   a Space URL
+ * @returns {string}
+ * @throws {ValidationError}   when `spaceUrl` is not a Space URL (see
+ *   {@link canonicalSpaceUrl}), is an origin root, or its last segment is a
+ *   malformed percent escape
+ */
+export declare function spaceIdOfUrl(spaceUrl: string): string;
+/**
+ * {@link spaceIdOfUrl} for a Space URL already in canonical form (a handle's
+ * `url`, the result of {@link canonicalSpaceUrl}), sparing the second parse.
+ * Returns `undefined` for an origin root, which has no id segment.
+ *
+ * @param canonical {string}   a canonical Space URL
+ * @returns {string | undefined}
+ * @throws {ValidationError}   when the last segment is a malformed percent
+ *   escape
+ */
+export declare function spaceIdOfCanonicalUrl(canonical: string): string | undefined;
+/**
+ * `{spaceUrl}meta` -- the Space Metadata object: the Space's description
  * (`name`, `controller`, `type`), read with `GET` and replaced with `PUT`.
+ * The Space container itself (the canonical Space URL) is the target a Space
+ * root capability names, the URL whose `GET` lists the Space's Collections,
+ * whose `POST` creates one, and whose `DELETE` removes the Space; it has no
+ * builder, since the caller holds it.
  *
- * @param spaceId {string}
+ * @param options {object}
+ * @param options.spaceUrl {string}
  * @returns {string}
  */
-export declare function spaceMeta(spaceId: string): string;
+export declare function spaceMetaUrl({ spaceUrl }: {
+    spaceUrl: string;
+}): string;
 /**
- * `/space/:spaceId/export` -- export a space as a tar archive.
+ * `{spaceUrl}export` -- export a space as a tar archive.
+ *
+ * @param options {object}
+ * @param options.spaceUrl {string}
+ * @returns {string}
  */
-export declare function spaceExport(spaceId: string): string;
+export declare function spaceExportUrl({ spaceUrl }: {
+    spaceUrl: string;
+}): string;
 /**
- * `/space/:spaceId/import` -- import a tar archive into a space.
+ * `{spaceUrl}import` -- import a tar archive into a space.
+ *
+ * @param options {object}
+ * @param options.spaceUrl {string}
+ * @returns {string}
  */
-export declare function spaceImport(spaceId: string): string;
+export declare function spaceImportUrl({ spaceUrl }: {
+    spaceUrl: string;
+}): string;
 /**
- * `/space/:spaceId/backends` -- the backends available within a space (list, and
+ * `{spaceUrl}backends` -- the backends available within a space (list, and
  * register a new `external` backend).
+ *
+ * @param options {object}
+ * @param options.spaceUrl {string}
+ * @returns {string}
  */
-export declare function spaceBackends(spaceId: string): string;
+export declare function spaceBackendsUrl({ spaceUrl }: {
+    spaceUrl: string;
+}): string;
 /**
- * `/space/:spaceId/backends/:backendId` -- a single registered `external`
- * backend (replace / deregister by id).
+ * `{spaceUrl}backends/{backendId}` -- a single registered `external` backend
+ * (replace / deregister by id).
+ *
+ * @param options {object}
+ * @param options.spaceUrl {string}
+ * @param options.backendId {string}
+ * @returns {string}
  */
-export declare function registeredBackend(spaceId: string, backendId: string): string;
+export declare function registeredBackendUrl({ spaceUrl, backendId }: {
+    spaceUrl: string;
+    backendId: string;
+}): string;
 /**
- * `/space/:spaceId/quotas` -- the space-level storage quota report.
+ * `{spaceUrl}quotas` -- the space-level storage quota report.
+ *
+ * @param options {object}
+ * @param options.spaceUrl {string}
+ * @returns {string}
  */
-export declare function spaceQuotas(spaceId: string): string;
+export declare function spaceQuotasUrl({ spaceUrl }: {
+    spaceUrl: string;
+}): string;
 /**
- * `/space/:spaceId/policy` -- the space-level access-control policy resource.
+ * `{spaceUrl}policy` -- the space-level access-control policy resource.
+ *
+ * @param options {object}
+ * @param options.spaceUrl {string}
+ * @returns {string}
  */
-export declare function spacePolicy(spaceId: string): string;
+export declare function spacePolicyUrl({ spaceUrl }: {
+    spaceUrl: string;
+}): string;
 /**
- * `/space/:spaceId/linkset` -- the space-level linkset (policy discovery).
+ * `{spaceUrl}linkset` -- the space-level linkset (policy discovery).
+ *
+ * @param options {object}
+ * @param options.spaceUrl {string}
+ * @returns {string}
  */
-export declare function spaceLinkset(spaceId: string): string;
+export declare function spaceLinksetUrl({ spaceUrl }: {
+    spaceUrl: string;
+}): string;
 /**
- * `/space/:spaceId/replicas` -- the Space's replica registrations: `GET` lists
- * them and `POST` registers one. Controller-only, both forms.
+ * `{spaceUrl}replicas` -- the Space's replica registrations: `GET` lists them
+ * and `POST` registers one. Controller-only, both forms.
+ *
+ * @param options {object}
+ * @param options.spaceUrl {string}
+ * @returns {string}
  */
-export declare function spaceReplicas(spaceId: string): string;
+export declare function spaceReplicasUrl({ spaceUrl }: {
+    spaceUrl: string;
+}): string;
 /**
- * `/space/:spaceId/replicas/:replicaId` -- one replica registration (read and
+ * `{spaceUrl}replicas/{replicaId}` -- one replica registration (read and
  * delete by id).
+ *
+ * @param options {object}
+ * @param options.spaceUrl {string}
+ * @param options.replicaId {string}
+ * @returns {string}
  */
-export declare function replicaRegistration(spaceId: string, replicaId: string): string;
+export declare function replicaRegistrationUrl({ spaceUrl, replicaId }: {
+    spaceUrl: string;
+    replicaId: string;
+}): string;
 /**
- * `/space/:spaceId/replicas/:replicaId/status` -- the pull loop's runtime
- * state for one registration.
+ * `{spaceUrl}replicas/{replicaId}/status` -- the pull loop's runtime state
+ * for one registration.
+ *
+ * @param options {object}
+ * @param options.spaceUrl {string}
+ * @param options.replicaId {string}
+ * @returns {string}
  */
-export declare function replicaStatus(spaceId: string, replicaId: string): string;
+export declare function replicaStatusUrl({ spaceUrl, replicaId }: {
+    spaceUrl: string;
+    replicaId: string;
+}): string;
 /**
- * `/space/:spaceId/zcaps/revocations/:capabilityId` -- submit a revocation of a
+ * `{spaceUrl}zcaps/revocations/{capabilityId}` -- submit a revocation of a
  * Space-rooted capability. The capability's `id` (typically a `urn:uuid:`) is
  * percent-encoded into the single final segment. `zcaps` is in the Reserved
  * Path Segment Registry, so no Collection can take that slot.
+ *
+ * @param options {object}
+ * @param options.spaceUrl {string}
+ * @param options.capabilityId {string}
+ * @returns {string}
  */
-export declare function spaceRevocation(spaceId: string, capabilityId: string): string;
+export declare function spaceRevocationUrl({ spaceUrl, capabilityId }: {
+    spaceUrl: string;
+    capabilityId: string;
+}): string;
 /**
- * `/space/:spaceId/:collectionId/` -- the Collection container in canonical
- * form: the target a "share this collection" capability names, the URL whose
- * `GET` lists its Resources, whose `POST` adds one, and whose `DELETE` removes
- * the Collection.
+ * `{spaceUrl}{collectionId}/` -- the Collection container in canonical form:
+ * the target a "share this collection" capability names, the URL whose `GET`
+ * lists its Resources, whose `POST` adds one, and whose `DELETE` removes the
+ * Collection.
  *
- * @param spaceId {string}
- * @param collectionId {string}
+ * @param options {object}
+ * @param options.spaceUrl {string}
+ * @param options.collectionId {string}
  * @returns {string}
  */
-export declare function collectionPath(spaceId: string, collectionId: string): string;
+export declare function collectionUrl({ spaceUrl, collectionId }: {
+    spaceUrl: string;
+    collectionId: string;
+}): string;
 /**
- * `/space/:spaceId/:collectionId/policy` -- the collection-level access-control
+ * `{spaceUrl}{collectionId}/policy` -- the collection-level access-control
  * policy resource.
+ *
+ * @param options {object}
+ * @param options.spaceUrl {string}
+ * @param options.collectionId {string}
+ * @returns {string}
  */
-export declare function collectionPolicy(spaceId: string, collectionId: string): string;
+export declare function collectionPolicyUrl({ spaceUrl, collectionId }: {
+    spaceUrl: string;
+    collectionId: string;
+}): string;
 /**
- * `/space/:spaceId/:collectionId/linkset` -- the collection-level linkset
- * (policy discovery).
+ * `{spaceUrl}{collectionId}/linkset` -- the collection-level linkset (policy
+ * discovery).
+ *
+ * @param options {object}
+ * @param options.spaceUrl {string}
+ * @param options.collectionId {string}
+ * @returns {string}
  */
-export declare function collectionLinkset(spaceId: string, collectionId: string): string;
+export declare function collectionLinksetUrl({ spaceUrl, collectionId }: {
+    spaceUrl: string;
+    collectionId: string;
+}): string;
 /**
- * `/space/:spaceId/:collectionId/backend` -- the "Collection Backend Selected"
+ * `{spaceUrl}{collectionId}/backend` -- the "Collection Backend Selected"
  * descriptor (the backend this collection is stored on).
+ *
+ * @param options {object}
+ * @param options.spaceUrl {string}
+ * @param options.collectionId {string}
+ * @returns {string}
  */
-export declare function collectionBackend(spaceId: string, collectionId: string): string;
+export declare function collectionBackendUrl({ spaceUrl, collectionId }: {
+    spaceUrl: string;
+    collectionId: string;
+}): string;
 /**
- * `/space/:spaceId/:collectionId/quota` -- the per-collection storage quota
- * report (spec "Quotas").
+ * `{spaceUrl}{collectionId}/quota` -- the per-collection storage quota report
+ * (spec "Quotas").
+ *
+ * @param options {object}
+ * @param options.spaceUrl {string}
+ * @param options.collectionId {string}
+ * @returns {string}
  */
-export declare function collectionQuota(spaceId: string, collectionId: string): string;
+export declare function collectionQuotaUrl({ spaceUrl, collectionId }: {
+    spaceUrl: string;
+    collectionId: string;
+}): string;
 /**
- * `/space/:spaceId/:collectionId/meta` -- the Collection Metadata object: the
+ * `{spaceUrl}{collectionId}/meta` -- the Collection Metadata object: the
  * Collection's configuration (`name`, `backend`, `encryption`, `generator`)
  * together with the server-managed timestamps / `createdBy` and the
  * user-writable `custom` and `epoch`, as one object under one validator.
+ *
+ * @param options {object}
+ * @param options.spaceUrl {string}
+ * @param options.collectionId {string}
+ * @returns {string}
  */
-export declare function collectionMeta(spaceId: string, collectionId: string): string;
+export declare function collectionMetaUrl({ spaceUrl, collectionId }: {
+    spaceUrl: string;
+    collectionId: string;
+}): string;
 /**
- * `/space/:spaceId/:collectionId/meta/log` -- the Collection's governing
- * history log sub-resource (JSON Lines). Not a Resource of the Collection:
- * absent from listings and the `changes` feed, and versioned by its own ETag.
+ * `{spaceUrl}{collectionId}/meta/log` -- the Collection's governing history
+ * log sub-resource (JSON Lines). Not a Resource of the Collection: absent from
+ * listings and the `changes` feed, and versioned by its own ETag.
+ *
+ * @param options {object}
+ * @param options.spaceUrl {string}
+ * @param options.collectionId {string}
+ * @returns {string}
  */
-export declare function collectionLog(spaceId: string, collectionId: string): string;
+export declare function collectionLogUrl({ spaceUrl, collectionId }: {
+    spaceUrl: string;
+    collectionId: string;
+}): string;
 /**
- * `/space/:spaceId/:collectionId/query` -- the collection-level query endpoint,
+ * `{spaceUrl}{collectionId}/query` -- the collection-level query endpoint,
  * whose body's `profile` selects the query (e.g. `changes`, `blinded-index`).
+ *
+ * @param options {object}
+ * @param options.spaceUrl {string}
+ * @param options.collectionId {string}
+ * @returns {string}
  */
-export declare function collectionQuery(spaceId: string, collectionId: string): string;
+export declare function collectionQueryUrl({ spaceUrl, collectionId }: {
+    spaceUrl: string;
+    collectionId: string;
+}): string;
 /**
- * `/space/:spaceId/:collectionId/:resourceId` -- get / put / delete a resource
+ * `{spaceUrl}{collectionId}/{resourceId}` -- get / put / delete a resource
  * (no trailing slash).
- */
-export declare function resourcePath(spaceId: string, collectionId: string, resourceId: string): string;
-/**
- * `/space/:spaceId/:collectionId/:resourceId/meta` -- the resource metadata
- * object (server-managed properties plus the user-writable `custom` object).
- */
-export declare function resourceMeta(spaceId: string, collectionId: string, resourceId: string): string;
-/**
- * `/space/:spaceId/:collectionId/:resourceId/policy` -- the resource-level
- * access-control policy resource.
- */
-export declare function resourcePolicy(spaceId: string, collectionId: string, resourceId: string): string;
-/**
- * `/space/:spaceId/:collectionId/:resourceId/chunks/:chunkIndex` -- a single
- * stored chunk of a chunked Resource. Member
- * form, no trailing slash: get / put / delete one chunk by its ordinal index.
- * The `chunkIndex` is a non-negative integer, emitted verbatim (it is never a
- * reserved or dot segment, so it needs no percent-encoding).
  *
- * @param spaceId {string}
- * @param collectionId {string}
- * @param resourceId {string}
- * @param chunkIndex {number}
+ * @param options {object}
+ * @param options.spaceUrl {string}
+ * @param options.collectionId {string}
+ * @param options.resourceId {string}
  * @returns {string}
  */
-export declare function resourceChunkPath(spaceId: string, collectionId: string, resourceId: string, chunkIndex: number): string;
+export declare function resourceUrl({ spaceUrl, collectionId, resourceId }: {
+    spaceUrl: string;
+    collectionId: string;
+    resourceId: string;
+}): string;
 /**
- * `/space/:spaceId/:collectionId/:resourceId/chunks/` -- the chunk container
- * of a chunked Resource: its stored chunks, listed. Container form, trailing
- * slash (the member form, {@link resourceChunkPath}, has none).
+ * `{spaceUrl}{collectionId}/{resourceId}/meta` -- the resource metadata
+ * object (server-managed properties plus the user-writable `custom` object).
  *
- * @param spaceId {string}
- * @param collectionId {string}
- * @param resourceId {string}
+ * @param options {object}
+ * @param options.spaceUrl {string}
+ * @param options.collectionId {string}
+ * @param options.resourceId {string}
  * @returns {string}
  */
-export declare function resourceChunksPath(spaceId: string, collectionId: string, resourceId: string): string;
+export declare function resourceMetaUrl({ spaceUrl, collectionId, resourceId }: {
+    spaceUrl: string;
+    collectionId: string;
+    resourceId: string;
+}): string;
 /**
- * The Spaces Repository URL beneath a server base URL: the reserved `spaces`
- * segment at the server root, in canonical trailing-slash form. This is the
- * URL a `WasClient` is constructed with (its `serverUrl`), so a consumer that
- * holds only a Space or Collection URL forms the client's `serverUrl` from the
- * base `parseAbsoluteSpaceTarget` reads off it.
+ * `{spaceUrl}{collectionId}/{resourceId}/policy` -- the resource-level
+ * access-control policy resource.
  *
  * @param options {object}
- * @param options.baseUrl {string}   the server base URL
+ * @param options.spaceUrl {string}
+ * @param options.collectionId {string}
+ * @param options.resourceId {string}
  * @returns {string}
  */
-export declare function spacesUrl({ baseUrl }: {
-    baseUrl: string;
+export declare function resourcePolicyUrl({ spaceUrl, collectionId, resourceId }: {
+    spaceUrl: string;
+    collectionId: string;
+    resourceId: string;
 }): string;
 /**
- * The server base URL a Spaces Repository URL sits beneath: everything before
- * its final `spaces` segment, without a trailing slash, so
- * `https://host/was/spaces/` yields `https://host/was` and
- * `https://host/spaces/` yields `https://host`. A trailing run of slashes is
- * collapsed first, so `https://host/spaces` and `https://host/spaces//` read
- * the same. The result is in `URL` canonical form (lower-case host, default
- * port dropped), so two serializations of one URL compare equal.
+ * `{spaceUrl}{collectionId}/{resourceId}/chunks/{chunkIndex}` -- a single
+ * stored chunk of a chunked Resource. Member form, no trailing slash: get /
+ * put / delete one chunk by its ordinal index. The `chunkIndex` is a
+ * non-negative integer, emitted verbatim (it is never a reserved or dot
+ * segment, so it needs no percent-encoding).
  *
- * Returns `null` when `url` is not an absolute `http(s)` URL, its last path
- * segment is not `spaces`, it has an empty path segment (`https://host//spaces`),
- * or it carries a query or fragment; the caller chooses the error.
- *
- * @param url {string}   a Spaces Repository URL
- * @returns {string | null}
+ * @param options {object}
+ * @param options.spaceUrl {string}
+ * @param options.collectionId {string}
+ * @param options.resourceId {string}
+ * @param options.chunkIndex {number}
+ * @returns {string}
  */
-export declare function baseUrlOfSpacesUrl(url: string): string | null;
+export declare function resourceChunkUrl({ spaceUrl, collectionId, resourceId, chunkIndex }: {
+    spaceUrl: string;
+    collectionId: string;
+    resourceId: string;
+    chunkIndex: number;
+}): string;
 /**
- * Resolves a path against the server base URL, producing an absolute URL
- * string suitable for zcap `invocationTarget`s.
- *
- * The path is joined onto `baseUrl`'s path rather than its origin, so a WAS
- * deployment mounted under a sub-path (e.g. `https://host/was`) keeps that
- * prefix. A bare-origin `baseUrl` behaves as before.
+ * `{spaceUrl}{collectionId}/{resourceId}/chunks/` -- the chunk container of a
+ * chunked Resource: its stored chunks, listed. Container form, trailing slash
+ * (the member form, {@link resourceChunkUrl}, has none).
  *
  * @param options {object}
- * @param options.baseUrl {string}   the server base URL
- * @param options.path {string}        a leading-slash path (e.g. `/space/x`)
+ * @param options.spaceUrl {string}
+ * @param options.collectionId {string}
+ * @param options.resourceId {string}
  * @returns {string}
  */
-export declare function toUrl({ baseUrl, path }: {
-    baseUrl: string;
-    path: string;
+export declare function resourceChunksUrl({ spaceUrl, collectionId, resourceId }: {
+    spaceUrl: string;
+    collectionId: string;
+    resourceId: string;
 }): string;
 /**
- * Canonicalizes an absolute collection URL to its items/listing endpoint --
- * the trailing-slash form (`/space/:id/:collectionId/`). This module owns the
- * trailing-slash rules, so callers that receive a collection URL from outside
- * (e.g. a public link) normalize it here rather than re-encoding the rule.
+ * The canonical (trailing-slash) form of a container URL received from
+ * outside and requested as given: the Spaces Repository URL a service
+ * description advertises, a public Collection link. The bare form only
+ * 308-redirects, and a signed invocation does not survive the redirect, so
+ * the slash is added here before the URL is ever requested. This module owns
+ * the trailing-slash rules; callers normalize here rather than re-encoding
+ * the rule.
  *
- * @param collectionUrl {string}   an absolute collection URL
+ * @param url {string}   an absolute container URL, in either form
  * @returns {string}
  */
-export declare function collectionItemsUrl(collectionUrl: string): string;
+export declare function canonicalContainerUrl(url: string): string;
 /**
- * The classification of a WAS pathname by the depth it addresses. The three
- * containment kinds map onto navigational handles; `sub-resource` covers every
- * reserved sub-endpoint the builders above produce (`/space/:id/policy`,
- * `/space/:id/:c/backend`, `/space/:id/:c/:r/meta`, ...), which has no handle of
- * its own.
+ * The classification of a URL beneath a Space by the depth it addresses. The
+ * three containment kinds map onto navigational handles; `sub-resource`
+ * covers every reserved sub-endpoint the builders above produce (`policy`,
+ * `{c}/backend`, `{c}/{r}/meta`, ...), which has no handle of its own.
  */
 export type ParsedSpacePath = {
     kind: 'space';
-    spaceId: string;
 } | {
     kind: 'collection';
-    spaceId: string;
     collectionId: string;
 } | {
     kind: 'resource';
-    spaceId: string;
     collectionId: string;
     resourceId: string;
 } | {
     kind: 'sub-resource';
-    spaceId: string;
     segments: string[];
 };
 /**
- * Classifies an absolute `target` URL that is expected to live on this server,
- * relative to `baseUrl`'s base path -- so a WAS mounted under a sub-path (e.g.
- * `https://host/was/`) resolves just as a bare-origin deployment does, which
- * `parseSpacePath` alone cannot do (it would see a leading `was` segment).
+ * Classifies an absolute `target` URL by where it sits beneath `spaceUrl`:
+ * the Space itself, one of its Collections, a Resource, or a reserved
+ * sub-endpoint. The inverse of the builders above, kept next to them so the
+ * grammar is owned in one place: `WasClient.fromCapability` reads a
+ * capability's `invocationTarget` through it, and the builders stay in
+ * lockstep.
+ *
+ * Both URLs are compared in parsed form, so a target serialized by another
+ * party (an upper-case host, a default port) still matches. Segments are
+ * percent-decoded (the builders re-encode them). Empty segments are dropped,
+ * so a container addressed in either form classifies the same: the bare and
+ * the trailing-slash form of a Collection are both the Collection. That is
+ * deliberate: the builders emit only the canonical form, but the targets
+ * parsed here come from capabilities minted elsewhere, and a client that
+ * reads only one form would refuse valid ones.
  *
- * Returns `null` when `target` is not beneath `baseUrl` (another origin, or
- * another base path), carries a query or fragment, or addresses something
- * outside the `/space` tree (e.g. `/kms`). The caller chooses whether that is
- * an error.
+ * Returns `null` when `target` is not beneath `spaceUrl` (another origin, or
+ * another path), carries a query or fragment, or either URL is malformed.
+ * The caller chooses whether that is an error.
  *
  * @param options {object}
- * @param options.baseUrl {string}   the client's server base URL
- * @param options.target {string}      an absolute URL on that server
+ * @param options.spaceUrl {string}   the Space URL
+ * @param options.target {string}     an absolute URL expected beneath it
  * @returns {ParsedSpacePath | null}
  */
-export declare function parseSpaceTarget({ baseUrl, target }: {
-    baseUrl: string;
+export declare function parseSpaceTarget({ spaceUrl, target }: {
+    spaceUrl: string;
     target: string;
 }): ParsedSpacePath | null;
-/**
- * Classifies an absolute `target` URL whose server is not known in advance:
- * the base URL is read off the target itself, as everything before its first
- * `space` path segment, so a WAS mounted under a sub-path
- * (`https://host/was/space/...`) yields `https://host/was`. For a target on a
- * known server, `parseSpaceTarget` is the stricter check (it refuses a target
- * beneath any other base). This is the one for a capability received from
- * another party, whose `invocationTarget` may name any host.
- *
- * Returns `null` when `target` is not an absolute `http(s)` URL, has no
- * `space` segment, carries a query or fragment, or has an empty segment in
- * the base before it (`https://host//was/space/x`); these are the rules
- * `baseUrlOfSpacesUrl` applies too. Also `null` from the path grammar for a
- * path it cannot classify. The caller chooses whether that is an error.
- *
- * @param target {string}   an absolute WAS URL
- * @returns {{ baseUrl: string; path: ParsedSpacePath } | null}   the server
- *   base URL (no trailing slash) and the parsed target beneath it
- */
-export declare function parseAbsoluteSpaceTarget(target: string): {
-    baseUrl: string;
-    path: ParsedSpacePath;
-} | null;
-/**
- * Parses a server pathname back into the containment depth it addresses -- the
- * inverse of the builders above, kept next to them so the grammar is owned in
- * one place. Segments are percent-decoded (the builders re-encode them).
- * Returns `null` for a pathname outside the `/space/...` tree; the caller
- * chooses the error. A path that addresses a reserved sub-endpoint rather than
- * a space/collection/resource -- e.g. `/space/s/policy`, `/space/s/c/backend`,
- * or any 5-segment target like `/space/s/c/r/meta` -- is classified
- * `sub-resource`, never silently truncated to the nearest handle.
- *
- * Empty segments are dropped, so a container addressed in either form
- * classifies the same: `/space/s` and `/space/s/` are both the Space, and
- * `/space/s/c` and `/space/s/c/` both the Collection. That is deliberate. The
- * builders emit only the canonical trailing-slash form, but the targets parsed
- * here come from capabilities minted elsewhere, and a client that reads only
- * one spelling would refuse valid ones.
- *
- * @param pathname {string}   a URL pathname (e.g. from `new URL(...).pathname`)
- * @returns {ParsedSpacePath | null}
- */
-export declare function parseSpacePath(pathname: string): ParsedSpacePath | null;
 //# sourceMappingURL=paths.d.ts.map