@sockethub/activity-streams 4.4.0-alpha.4 → 4.4.0-alpha.5

package/README.md

@@ -1,13 +1,24 @@
-# @sockethub/activity-streams.js
+# @sockethub/activity-streams
 
 [![License](https://img.shields.io/npm/l/activity-streams.svg?style=flat)](https://npmjs.org/package/@sockethub/activity-streams)
 [![Downloads](http://img.shields.io/npm/dm/activity-streams.svg?style=flat)](https://npmjs.org/package/@sockethub/activity-streams)
 
-A simple tool to facilitate handling and referencing activity streams and it's objects, cutting down on verbosity.
+A simple tool to facilitate handling and referencing activity streams and its objects, cutting
+down on verbosity.
 
-Designed to run in both `node.js` and the `browser`.
+Designed to run in both `node.js`, `bun` and the `browser`.
 
-I am learning about JSON-LD and ActivityStreams2 as I write this library, so suggestions for improvement are very welcome.
+This is a WIP and not fully JSON-LD or ActivityStreams2 compliant, suggestions for improvement
+are very welcome.
+
+## What it does
+
+This library helps you:
+
+- **Create and store** ActivityStream objects with validation
+- **Auto-expand** string references into full objects (e.g., `"user@example.com"` becomes `{id: "user@example.com"}`)
+- **Build Activity Streams** that automatically link to stored objects
+- **Listen for events** when objects are created or deleted
 
 ## Install
 
@@ -15,19 +26,93 @@ I am learning about JSON-LD and ActivityStreams2 as I write this library, so sug
 
 `$ npm install @sockethub/activity-streams`
 
+### Bun
+
+`$ bun install @sockethub/activity-streams`
+
+#### CommonJS
+
 ```javascript
 const ASFactory = require('@sockethub/activity-streams');
 const ActivityStreams = ASFactory({
-  failOnUnkownObjectProperties: false // default
+  failOnUnknownObjectProperties: false // default
+});
+```
+
+#### ESM
+
+```javascript
+import { ASFactory } from '@sockethub/activity-streams';
+const ActivityStreams = ASFactory({
+  failOnUnknownObjectProperties: false // default
 });
 ```
 
 ### Browser
 
-`<script src="http://example.com/activity-streams.js"></script>`
+The browser bundle is available in the dist folder:
 
-Once included in a web-page, the `ActivityStreams` base object should be on the global scope, with the sub-properties `ActivityStreams.Object` and `ActivityStreams.Stream`.
+```javascript
+import '@sockethub/activity-streams/dist/activity-streams.js';
+```
+
+You can place it somewhere accessible from the web and include it via a `script` tag.
+
+```javascript
+<script src="http://example.com/activity-streams.js" type="module"></script>
+```
 
+Once included in a web-page, the `ActivityStreams` base object should be on the global scope, with
+the sub-properties `ActivityStreams.Object` and `ActivityStreams.Stream`.
+
+## Quick Start
+
+### Standalone Usage
+
+```javascript
+import { ASFactory } from '@sockethub/activity-streams';
+const ActivityStreams = ASFactory();
+
+// Create an object
+const user = ActivityStreams.Object.create({
+  id: "user@example.com",
+  type: "person",
+  name: "John Doe"
+});
+
+// Create an activity that references it
+const activity = ActivityStreams.Stream({
+  type: "send",
+  context: "irc",
+  actor: "user@example.com",  // automatically expands to full object
+  object: { type: "message", content: "Hello!" }
+});
+```
+
+### With Sockethub Client
+
+If you're using the Sockethub client, this library is already bundled and available:
+
+```javascript
+import SockethubClient from '@sockethub/client';
+
+const socket = io('http://localhost:10550');
+const sockethubClient = new SockethubClient(socket);
+
+// Access ActivityStreams through the client
+const user = sockethubClient.ActivityStreams.Object.create({
+  id: "user@example.com", 
+  type: "person",
+  name: "John Doe"
+});
+
+const activity = sockethubClient.ActivityStreams.Stream({
+  type: "send",
+  context: "irc",
+  actor: "user@example.com",
+  object: { type: "message", content: "Hello!" }
+});
+```
 
 ## Example
 
@@ -74,7 +159,7 @@ const exampleUser = ActivityStreams.Object.get('irc://exampleUser@irc.freenode.n
     //  }
 
 ActivityStreams.Stream({
-  context: 'send',
+  type: 'send',
   actor: 'irc://exampleUser@irc.freenode.net',
   object: {
     type: "message",
@@ -84,7 +169,7 @@ ActivityStreams.Stream({
 });
     // ... returns:
     //  {
-    //    '@context': 'send',
+    //    type: 'send',
     //    actor: {
     //      id: 'irc://exampleUser@irc.freenode.net',
     //      type: "person",
@@ -108,3 +193,18 @@ ActivityStreams.Stream({
     //    }
     //  }
 ```
+
+## Error Handling
+
+The library provides clear error messages when validation fails:
+
+```javascript
+// This will throw: "ActivityStreams validation failed: the 'object' property is null"
+ActivityStreams.Object.create(null);
+
+// This will throw: "ActivityStreams validation failed: the 'object' property received string..."
+ActivityStreams.Object.create("just-a-string");
+
+// This will throw: "ActivityStreams validation failed: property 'foo' with value 'bar' is not allowed..."
+ActivityStreams.Object.create({ id: "test", foo: "bar" });
+```