From bb4a95e8de026d5f72860e554d358da521d5fe57 Mon Sep 17 00:00:00 2001
From: Lukas Rosenstock <lukas@rosenstock.email>
Date: Fri, 16 Oct 2026 09:04:50 +0000
Subject: [PATCH] Extended documentation

---
 README.md       | 24 ++++++++++++++++++++++--
 docs/options.md | 16 ++++++++++++++++
 2 files changed, 38 insertions(+), 2 deletions(-)
 create mode 100644 docs/options.md

diff --git a/README.md b/README.md
index 84ebc38..b92c96c 100644
--- a/README.md
+++ b/README.md
@@ -29,6 +29,26 @@ $object = $retriever->getCloudObject(new IRI('coid://cloudobjects.io'));
 echo $object->getLabel();
 ```
 
+When no options are passed to the `ObjectRetriever`, it will initialize with default settings and no authentication, which means that it can only retrieve public triples from public objects. You can authenticate with a CloudObjects namespace (domain name) and the shared secret between this namespace and CloudObjects.
+
+```php
+use CloudObjects\SDK\ObjectRetriever;
+use ML\IRI\IRI;
+
+$retriever = new ObjectRetriever([
+    'auth_ns' => 'example.com',
+    'auth_secret' => 'YOUR_SHARED_SECRET',
+]);
+
+$object = $retriever->getCloudObject(new IRI('coid://example.com/PrivateObject'));
+
+// Retrieve the object describing the authenticating namespace itself
+$namespace = $retriever->getAuthenticatingNamespaceCloudObject();
+echo $namespace->getLabel();
+```
+
+Any production usage should configure a cache; [all the caching options are documented here](docs/caching.md). Other [options are documented here](docs/options.md).
+
 ### Using the static facade
 
 ```php
@@ -36,7 +56,7 @@ use CloudObjects\SDK\ObjectRetriever;
 use CloudObjects\SDK\ObjectRetrieverFacade;
 use ML\IRI\IRI;
 
-ObjectRetrieverFacade::setObjectRetriever(new ObjectRetriever());
+ObjectRetrieverFacade::setObjectRetriever(new ObjectRetriever);
 
 $object = ObjectRetrieverFacade::getCloudObject(new IRI('coid://cloudobjects.io'));
 echo $object->getLabel();
@@ -50,7 +70,7 @@ The global function uses the static facade, so the facade must be initialized fi
 use CloudObjects\SDK\ObjectRetriever;
 use CloudObjects\SDK\ObjectRetrieverFacade;
 
-ObjectRetrieverFacade::setObjectRetriever(new ObjectRetriever());
+ObjectRetrieverFacade::setObjectRetriever(new ObjectRetriever);
 
 $object = cloudobjects_get_object('coid://cloudobjects.io');
 echo $object->getLabel();
diff --git a/docs/options.md b/docs/options.md
new file mode 100644
index 0000000..0850c69
--- /dev/null
+++ b/docs/options.md
@@ -0,0 +1,16 @@
+## Options
+
+The `ObjectRetriever` constructor accepts an associative array of options. All options are optional; any option not specified uses its default value.
+
+| Key | Description | Default value |
+| --- | --- | --- |
+| `cache_storage` | External cache storage; must implement `Kevinrob\GuzzleCache\Storage\CacheStorageInterface`, `Psr\Cache\CacheItemPoolInterface` or `Psr\SimpleCache\CacheInterface`. See [caching](caching.md). | `null` |
+| `cache_prefix` | Prefix for all keys written to the external cache. | `'clobj:'` |
+| `cache_ttl` | Number of seconds that object descriptions are cached, both in memory and in the external cache. | `60` |
+| `static_config_path` | Path to a directory with static object descriptions, which are used instead of the API. Objects are read from `<path>/<namespace>/<path of COID>/object.jsonld`. | `null` |
+| `auth_ns` | Hostname of the namespace to authenticate as, e.g. `example.com`. | `null` |
+| `auth_secret` | Shared secret between the authenticating namespace and CloudObjects. | `null` |
+| `api_base_url` | Base URL of the CloudObjects Core Object API. If not set, `https://od.coid.link/` is used. | `null` |
+| `logger` | Logger implementing `Psr\Log\LoggerInterface`, which receives info messages about object retrieval. | `null` |
+| `timeout` | Total timeout for API requests, in seconds. | `20` |
+| `connect_timeout` | Timeout for establishing a connection to the API, in seconds. | `5` |