@colibri-social/lexicons 0.1.0

package/lexicons/com/atproto/space/getRepo.json

@@ -0,0 +1,41 @@
+{
+  "lexicon": 1,
+  "id": "com.atproto.space.getRepo",
+  "defs": {
+    "main": {
+      "type": "query",
+      "description": "Download an account's permissioned repo within a space as a CAR file, for full-state recovery. The CAR declares two roots in order: the signed commit, then a DRISL (DAG-CBOR) index mapping '{collection}/{rkey}' to record CID. Record blocks follow, in the same canonical DAG-CBOR key order as the index (length-first, then bytewise). Blobs are not included and are fetched separately via getBlob. Served by a repo host. Callable with either OAuth (for the authenticated user's own data) or a space credential (for syncing services).",
+      "parameters": {
+        "type": "params",
+        "required": ["space", "repo"],
+        "properties": {
+          "space": {
+            "type": "string",
+            "format": "space-ref",
+            "description": "Reference to the space."
+          },
+          "repo": {
+            "type": "string",
+            "format": "did",
+            "description": "The DID of the account whose repo to download."
+          },
+          "excludeValues": {
+            "type": "boolean",
+            "default": false,
+            "description": "If true, omit the record blocks and return only the commit and index roots. The index is still fully authenticated by folding its entries into a set hash and comparing against the commit, so a syncer can diff it against a local copy and fetch just the records it lacks. Note the resulting CAR declares two roots and carries no non-root blocks."
+          }
+        }
+      },
+      "output": {
+        "encoding": "application/vnd.ipld.car"
+      },
+      "errors": [
+        { "name": "SpaceNotFound" },
+        { "name": "RepoNotFound" },
+        { "name": "RepoTakendown" },
+        { "name": "RepoSuspended" },
+        { "name": "RepoDeactivated" }
+      ]
+    }
+  }
+}

package/lexicons/com/atproto/space/getSpaceCredential.json

@@ -0,0 +1,67 @@
+{
+  "lexicon": 1,
+  "id": "com.atproto.space.getSpaceCredential",
+  "defs": {
+    "main": {
+      "type": "procedure",
+      "description": "Exchange a delegation token for a space credential. Called on the space authority, with the delegation token as the request's authorization token and a DPoP proof signed by the key to bind the credential to. The resulting space credential reads repos across the space. Requires a delegation token and DPoP proof, plus a client attestation when the space gates on app identity.",
+      "input": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "required": ["space"],
+          "properties": {
+            "space": {
+              "type": "string",
+              "format": "space-ref",
+              "description": "Reference to the space."
+            },
+            "clientAttestation": {
+              "type": "string",
+              "description": "Optional client attestation JWT establishing the app's identity. Required only when the space gates on app identity."
+            }
+          }
+        }
+      },
+      "output": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "required": ["credential"],
+          "properties": {
+            "credential": {
+              "type": "string",
+              "description": "A signed JWT space credential, bound through its cnf.jkt claim to the key that signed the request's DPoP proof."
+            }
+          }
+        }
+      },
+      "errors": [
+        {
+          "name": "SpaceNotFound"
+        },
+        {
+          "name": "SpaceDeleted"
+        },
+        {
+          "name": "UserNotAuthorized",
+          "description": "Refused on the basis of the requesting user."
+        },
+        {
+          "name": "AppNotAuthorized",
+          "description": "Refused on the basis of the requesting app."
+        },
+        {
+          "name": "NotAuthorized",
+          "description": "Refused without attributing the refusal to the user or the app. Authorities that do not wish to disclose which perimeter failed may return this in place of UserNotAuthorized or AppNotAuthorized."
+        },
+        {
+          "name": "InvalidDelegationToken"
+        },
+        {
+          "name": "InvalidClientAttestation"
+        }
+      ]
+    }
+  }
+}

package/lexicons/com/atproto/space/listBlobs.json

@@ -0,0 +1,59 @@
+{
+  "lexicon": 1,
+  "id": "com.atproto.space.listBlobs",
+  "defs": {
+    "main": {
+      "type": "query",
+      "description": "List the CIDs of blobs referenced by an account's records within a permissioned space, optionally since some revision of that repo. Lets a syncer discover which blobs to fetch via getBlob, and lets an account enumerate the blobs it must carry when migrating a permissioned repo. Scoped to one space: blobs behind permissioned records are never enumerated by com.atproto.sync.listBlobs, which is unauthenticated. Callable with either OAuth (for the authenticated user's own data) or a space credential (for syncing services).",
+      "parameters": {
+        "type": "params",
+        "required": ["space", "repo"],
+        "properties": {
+          "space": {
+            "type": "string",
+            "format": "space-ref",
+            "description": "Reference to the space."
+          },
+          "repo": {
+            "type": "string",
+            "format": "did",
+            "description": "The DID of the account whose blobs to list."
+          },
+          "since": {
+            "type": "string",
+            "format": "tid",
+            "description": "Optional revision of the permissioned repo to list blobs since."
+          },
+          "limit": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 1000,
+            "default": 500
+          },
+          "cursor": { "type": "string" }
+        }
+      },
+      "output": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "required": ["cids"],
+          "properties": {
+            "cursor": { "type": "string" },
+            "cids": {
+              "type": "array",
+              "items": { "type": "string", "format": "cid" }
+            }
+          }
+        }
+      },
+      "errors": [
+        { "name": "SpaceNotFound" },
+        { "name": "RepoNotFound" },
+        { "name": "RepoTakendown" },
+        { "name": "RepoSuspended" },
+        { "name": "RepoDeactivated" }
+      ]
+    }
+  }
+}

package/lexicons/com/atproto/space/listRecords.json

@@ -0,0 +1,108 @@
+{
+  "lexicon": 1,
+  "id": "com.atproto.space.listRecords",
+  "defs": {
+    "main": {
+      "type": "query",
+      "description": "List the records in an account's repo within a permissioned space, optionally filtered by collection. By default each record's value is inlined; set excludeValues for a metadata-only listing (collection, rkey, cid). Used for full-state recovery. Callable with either OAuth (for the authenticated user's own data) or a space credential (for syncing services). Throws RepoNotFound when the account holds no repo in the space; this does not distinguish a member that has never written from a non-member.",
+      "parameters": {
+        "type": "params",
+        "required": ["space", "repo"],
+        "properties": {
+          "space": {
+            "type": "string",
+            "format": "space-ref",
+            "description": "Reference to the space."
+          },
+          "repo": {
+            "type": "string",
+            "format": "did",
+            "description": "The DID of the account whose repo to list."
+          },
+          "collection": {
+            "type": "string",
+            "format": "nsid",
+            "description": "The NSID of the record collection. If omitted, lists records across all collections."
+          },
+          "limit": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 1000,
+            "default": 50,
+            "description": "The number of records to return."
+          },
+          "cursor": {
+            "type": "string"
+          },
+          "reverse": {
+            "type": "boolean",
+            "description": "Flag to reverse the order of the returned records."
+          },
+          "excludeValues": {
+            "type": "boolean",
+            "default": false,
+            "description": "If true, omit inlined record values and return only metadata (collection, rkey, cid)."
+          }
+        }
+      },
+      "output": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "required": ["records"],
+          "properties": {
+            "cursor": {
+              "type": "string"
+            },
+            "records": {
+              "type": "array",
+              "items": {
+                "type": "ref",
+                "ref": "#record"
+              }
+            }
+          }
+        }
+      },
+      "errors": [
+        {
+          "name": "SpaceNotFound"
+        },
+        {
+          "name": "RepoNotFound"
+        },
+        {
+          "name": "RepoTakendown"
+        },
+        {
+          "name": "RepoSuspended"
+        },
+        {
+          "name": "RepoDeactivated"
+        }
+      ]
+    },
+    "record": {
+      "type": "object",
+      "required": ["collection", "rkey", "cid"],
+      "properties": {
+        "collection": {
+          "type": "string",
+          "format": "nsid"
+        },
+        "rkey": {
+          "type": "string",
+          "format": "record-key"
+        },
+        "cid": {
+          "type": "string",
+          "format": "cid"
+        },
+        "value": {
+          "type": "unknown",
+          "description": "The record's value. Inlined by default; omitted when excludeValues is set."
+        }
+      }
+    }
+  }
+}

package/lexicons/com/atproto/space/listRepoOps.json

@@ -0,0 +1,111 @@
+{
+  "lexicon": 1,
+  "id": "com.atproto.space.listRepoOps",
+  "defs": {
+    "main": {
+      "type": "query",
+      "description": "List the operation log for an account's permissioned repo within a space, returning operations after a given revision. Primary incremental sync mechanism. By default each created or updated operation inlines the record's current value; set excludeValues for metadata-only entries. Note the oplog is a transport optimization with no history guarantee: a host may compact it or drop it, and it does not survive account migration, so omitting `since` returns the retained window rather than the repo's full history. Use getRepo for an initial sync or when a `since` revision is no longer available. Callable with either OAuth (for the authenticated user's own data) or a space credential (for syncing services).",
+      "parameters": {
+        "type": "params",
+        "required": ["space", "repo"],
+        "properties": {
+          "space": {
+            "type": "string",
+            "format": "space-ref",
+            "description": "Reference to the space."
+          },
+          "repo": {
+            "type": "string",
+            "format": "did",
+            "description": "The DID of the account whose oplog to retrieve."
+          },
+          "since": {
+            "type": "string",
+            "format": "tid",
+            "description": "Return operations after this revision. The caller's own sync position; use `cursor` to continue a paginated response."
+          },
+          "limit": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 1000,
+            "default": 100,
+            "description": "Maximum number of operations to return."
+          },
+          "cursor": {
+            "type": "string",
+            "description": "Opaque pagination cursor from a previous response. Takes precedence over `since` when both are supplied."
+          },
+          "excludeValues": {
+            "type": "boolean",
+            "default": false,
+            "description": "If true, omit inlined record values and return only operation metadata."
+          }
+        }
+      },
+      "output": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "required": ["ops"],
+          "properties": {
+            "ops": {
+              "type": "array",
+              "items": {
+                "type": "ref",
+                "ref": "#opEntry"
+              }
+            },
+            "commit": {
+              "type": "ref",
+              "ref": "com.atproto.space.defs#signedCommit",
+              "description": "The account's current signed commit. Included when the response reaches the head of the oplog; omitted on backfill responses."
+            },
+            "cursor": {
+              "type": "string",
+              "description": "Pass as `cursor` to fetch the next page. Absent once the response reaches the head of the oplog."
+            }
+          }
+        }
+      },
+      "errors": [
+        { "name": "SpaceNotFound" },
+        { "name": "RepoNotFound" },
+        { "name": "RepoTakendown" },
+        { "name": "RepoSuspended" },
+        { "name": "RepoDeactivated" }
+      ]
+    },
+    "opEntry": {
+      "type": "object",
+      "description": "A single operation in a permissioned repo's oplog. cid is null for deletes; prev is null for creates. Operations sharing the same rev belong to the same batch. value carries the record's current value for creates and updates, unless excludeValues was set or the value is stale (superseded by a later operation).",
+      "required": ["rev", "collection", "rkey", "cid", "prev"],
+      "nullable": ["cid", "prev"],
+      "properties": {
+        "rev": {
+          "type": "string",
+          "format": "tid"
+        },
+        "collection": {
+          "type": "string",
+          "format": "nsid"
+        },
+        "rkey": {
+          "type": "string",
+          "format": "record-key"
+        },
+        "cid": {
+          "type": "string",
+          "format": "cid"
+        },
+        "prev": {
+          "type": "string",
+          "format": "cid"
+        },
+        "value": {
+          "type": "unknown",
+          "description": "The record's current value, inlined for create and update operations. Omitted when excludeValues is set, for deletes, or when the value has been superseded by a later operation."
+        }
+      }
+    }
+  }
+}

package/lexicons/com/atproto/space/listRepos.json

@@ -0,0 +1,75 @@
+{
+  "lexicon": 1,
+  "id": "com.atproto.space.listRepos",
+  "defs": {
+    "main": {
+      "type": "query",
+      "description": "List the known repos that hold data in a space (the writer set), with each repo's current rev and commit hash. Served by the space host. This is the sync boundary, not an access-control list: it enumerates only writers, never readers. The set is what the authority claims from write notifications and is not itself authoritative; a repo's host is the source of truth.",
+      "parameters": {
+        "type": "params",
+        "required": ["space"],
+        "properties": {
+          "space": {
+            "type": "string",
+            "format": "space-ref",
+            "description": "Reference to the space."
+          },
+          "limit": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 1000,
+            "default": 100,
+            "description": "Maximum number of repos to return."
+          },
+          "cursor": {
+            "type": "string"
+          }
+        }
+      },
+      "output": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "required": ["repos"],
+          "properties": {
+            "cursor": {
+              "type": "string"
+            },
+            "repos": {
+              "type": "array",
+              "items": {
+                "type": "ref",
+                "ref": "#repo"
+              }
+            }
+          }
+        }
+      },
+      "errors": [
+        {
+          "name": "SpaceNotFound"
+        }
+      ]
+    },
+    "repo": {
+      "type": "object",
+      "required": ["did", "rev", "hash"],
+      "properties": {
+        "did": {
+          "type": "string",
+          "format": "did",
+          "description": "The DID of a repo that holds data in the space."
+        },
+        "rev": {
+          "type": "string",
+          "description": "The repo's current revision (TID), as last reported to the authority. May lag the repo host, which is the source of truth.",
+          "format": "tid"
+        },
+        "hash": {
+          "type": "bytes",
+          "description": "The repo's current commit hash (sha256 of the LtHash state), as last reported to the authority."
+        }
+      }
+    }
+  }
+}

package/lexicons/com/atproto/space/listSpaces.json

@@ -0,0 +1,65 @@
+{
+  "lexicon": 1,
+  "id": "com.atproto.space.listSpaces",
+  "defs": {
+    "main": {
+      "type": "query",
+      "description": "List the spaces the authenticated user holds a repo in (i.e. spaces the user has written data to), optionally filtered by type and/or authority DID. Note this is not 'spaces I'm a member of' — a member's PDS only tracks spaces its user has written to. Requires auth, implemented by PDS.",
+      "parameters": {
+        "type": "params",
+        "properties": {
+          "type": {
+            "type": "string",
+            "format": "nsid",
+            "description": "Filter to spaces of this type."
+          },
+          "did": {
+            "type": "string",
+            "format": "did",
+            "description": "Filter to spaces under this authority DID."
+          },
+          "limit": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 100,
+            "default": 50,
+            "description": "The number of spaces to return."
+          },
+          "cursor": {
+            "type": "string"
+          }
+        }
+      },
+      "output": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "required": ["spaces"],
+          "properties": {
+            "cursor": {
+              "type": "string"
+            },
+            "spaces": {
+              "type": "array",
+              "items": {
+                "type": "ref",
+                "ref": "#spaceView"
+              }
+            }
+          }
+        }
+      }
+    },
+    "spaceView": {
+      "type": "object",
+      "required": ["uri"],
+      "properties": {
+        "uri": {
+          "type": "string",
+          "format": "space-ref",
+          "description": "URI of the space."
+        }
+      }
+    }
+  }
+}

package/lexicons/com/atproto/space/notifySpaceDeleted.json

@@ -0,0 +1,24 @@
+{
+  "lexicon": 1,
+  "id": "com.atproto.space.notifySpaceDeleted",
+  "defs": {
+    "main": {
+      "type": "procedure",
+      "description": "Notify a syncing service that a space has been deleted, and that it should drop every copy of the space's data it holds. Sent by the space authority to the services registered for the space, best-effort. Authenticated with service auth addressed to the receiving service.",
+      "input": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "required": ["space"],
+          "properties": {
+            "space": {
+              "type": "string",
+              "format": "space-ref",
+              "description": "Reference to the deleted space."
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/lexicons/com/atproto/space/notifyWrite.json

@@ -0,0 +1,38 @@
+{
+  "lexicon": 1,
+  "id": "com.atproto.space.notifyWrite",
+  "defs": {
+    "main": {
+      "type": "procedure",
+      "description": "Notify that a repo in a space has advanced to a new revision. Sent by a repo host to the space host, and forwarded to registered syncers. Best-effort. Authenticated with service auth.",
+      "input": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "required": ["space", "repo", "rev", "hash"],
+          "properties": {
+            "space": {
+              "type": "string",
+              "format": "space-ref",
+              "description": "Reference to the space."
+            },
+            "repo": {
+              "type": "string",
+              "format": "did",
+              "description": "The DID of the account whose repo advanced."
+            },
+            "rev": {
+              "type": "string",
+              "description": "The revision of the write.",
+              "format": "tid"
+            },
+            "hash": {
+              "type": "bytes",
+              "description": "The repo's current commit hash (sha256 of the LtHash state) after the write. Lets the space host maintain each repo's hash for listRepos."
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/lexicons/com/atproto/space/putRecord.json

@@ -0,0 +1,75 @@
+{
+  "lexicon": 1,
+  "id": "com.atproto.space.putRecord",
+  "defs": {
+    "main": {
+      "type": "procedure",
+      "description": "Write a record in a permissioned space, creating or updating it as needed. Requires auth, implemented by PDS.",
+      "input": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "required": ["space", "repo", "collection", "rkey", "record"],
+          "properties": {
+            "space": {
+              "type": "string",
+              "format": "space-ref",
+              "description": "Reference to the space."
+            },
+            "repo": {
+              "type": "string",
+              "format": "did",
+              "description": "The DID of the repo to write to (the authenticated member)."
+            },
+            "collection": {
+              "type": "string",
+              "format": "nsid",
+              "description": "The NSID of the record collection."
+            },
+            "rkey": {
+              "type": "string",
+              "format": "record-key",
+              "description": "The Record Key.",
+              "maxLength": 512
+            },
+            "validate": {
+              "type": "boolean",
+              "description": "Can be set to 'false' to skip Lexicon schema validation of record data, 'true' to require it, or leave unset to validate only for known Lexicons."
+            },
+            "record": {
+              "type": "unknown",
+              "description": "The record to write."
+            }
+          }
+        }
+      },
+      "output": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "required": ["uri", "cid"],
+          "properties": {
+            "uri": {
+              "type": "string",
+              "format": "at-uri",
+              "description": "URI of the written record."
+            },
+            "cid": {
+              "type": "string",
+              "format": "cid"
+            },
+            "validationStatus": {
+              "type": "string",
+              "knownValues": ["valid", "unknown"]
+            }
+          }
+        }
+      },
+      "errors": [
+        {
+          "name": "SpaceNotFound"
+        }
+      ]
+    }
+  }
+}