kennethnym/aris
1
0
Fork 0
mirror of https://github.com/kennethnym/aris.git synced 2026-03-20 00:51:20 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: add actions to FeedSource interface

Browse Source 
Add listActions() and executeAction() to FeedSource for write
operations back to external services. Actions use arktype schemas
for input validation via StandardSchemaV1.

- ActionDefinition type with optional input schema
- FeedEngine routes actions with existence and ID validation
- Source IDs use reverse-domain format (aris.location, aris.tfl)
- LocationSource: update-location action with schema validation
- TflSource: set-lines-of-interest action with lineId validation
- No-op implementations for sources without actions

Co-authored-by: Ona <no-reply@ona.com>
This commit is contained in:
Kenneth
2026-02-15 12:26:23 +00:00
parent 4d6cac7ec8
commit 699155e0d8
29 changed files with 1169 additions and 116 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
packages/aris-core/package.json
View File

@@ -6,5 +6,8 @@
"types": "src/index.ts",
"scripts": {
"test": "bun test ."
},
"dependencies": {
"@standard-schema/spec": "^1.1.0"
}
}

27
packages/aris-core/src/action.ts Normal file
View File

@@ -0,0 +1,27 @@
import type { StandardSchemaV1 } from "@standard-schema/spec"
/**
* Describes an action a source can perform.
*
* Action IDs use descriptive verb-noun kebab-case (e.g., "update-location", "play-track").
* Combined with the source's reverse-domain ID, they form a globally unique identifier:
* `<sourceId>/<actionId>` (e.g., "aris.location/update-location").
*/
export class UnknownActionError extends Error {
readonly actionId: string
constructor(actionId: string) {
super(`Unknown action: ${actionId}`)
this.name = "UnknownActionError"
this.actionId = actionId
}
}
export interface ActionDefinition<TInput = unknown> {
/** Descriptive action name in kebab-case (e.g., "update-location", "play-track") */
readonly id: string
/** Optional longer description */
readonly description?: string
/** Schema for input validation. Accepts any Standard Schema compatible validator (arktype, zod, valibot, etc.). */
readonly input?: StandardSchemaV1<TInput>
}

162
packages/aris-core/src/feed-engine.test.ts
View File

@@ -1,9 +1,19 @@
import { describe, expect, test } from "bun:test"
import type { Context, ContextKey, FeedItem, FeedSource } from "./index"
import type { ActionDefinition, Context, ContextKey, FeedItem, FeedSource } from "./index"
import { FeedEngine } from "./feed-engine"
import { contextKey, contextValue } from "./index"
import { UnknownActionError, contextKey, contextValue } from "./index"
// No-op action methods for test sources
const noActions = {
async listActions(): Promise<Record<string, ActionDefinition>> {
return {}
},
async executeAction(actionId: string): Promise<void> {
throw new UnknownActionError(actionId)
},
}
// =============================================================================
// CONTEXT KEYS
@@ -43,6 +53,7 @@ function createLocationSource(): SimulatedLocationSource {
return {
id: "location",
...noActions,
onContextUpdate(cb) {
callback = cb
@@ -71,6 +82,7 @@ function createWeatherSource(
return {
id: "weather",
dependencies: ["location"],
...noActions,
async fetchContext(context) {
const location = contextValue(context, LocationKey)
@@ -104,6 +116,7 @@ function createAlertSource(): FeedSource<AlertFeedItem> {
return {
id: "alert",
dependencies: ["weather"],
...noActions,
async fetchContext() {
return null
@@ -168,11 +181,12 @@ describe("FeedEngine", () => {
})
describe("graph validation", () => {
test("throws on missing dependency", () => {
test("throws on missing dependency", async () => {
const engine = new FeedEngine()
const orphan: FeedSource = {
id: "orphan",
dependencies: ["nonexistent"],
...noActions,
async fetchContext() {
return null
},
@@ -180,16 +194,17 @@ describe("FeedEngine", () => {
engine.register(orphan)
expect(engine.refresh()).rejects.toThrow(
await expect(engine.refresh()).rejects.toThrow(
'Source "orphan" depends on "nonexistent" which is not registered',
)
})
test("throws on circular dependency", () => {
test("throws on circular dependency", async () => {
const engine = new FeedEngine()
const a: FeedSource = {
id: "a",
dependencies: ["b"],
...noActions,
async fetchContext() {
return null
},
@@ -197,6 +212,7 @@ describe("FeedEngine", () => {
const b: FeedSource = {
id: "b",
dependencies: ["a"],
...noActions,
async fetchContext() {
return null
},
@@ -204,14 +220,15 @@ describe("FeedEngine", () => {
engine.register(a).register(b)
expect(engine.refresh()).rejects.toThrow("Circular dependency detected: a → b → a")
await expect(engine.refresh()).rejects.toThrow("Circular dependency detected: a → b → a")
})
test("throws on longer cycles", () => {
test("throws on longer cycles", async () => {
const engine = new FeedEngine()
const a: FeedSource = {
id: "a",
dependencies: ["c"],
...noActions,
async fetchContext() {
return null
},
@@ -219,6 +236,7 @@ describe("FeedEngine", () => {
const b: FeedSource = {
id: "b",
dependencies: ["a"],
...noActions,
async fetchContext() {
return null
},
@@ -226,6 +244,7 @@ describe("FeedEngine", () => {
const c: FeedSource = {
id: "c",
dependencies: ["b"],
...noActions,
async fetchContext() {
return null
},
@@ -233,7 +252,7 @@ describe("FeedEngine", () => {
engine.register(a).register(b).register(c)
expect(engine.refresh()).rejects.toThrow("Circular dependency detected")
await expect(engine.refresh()).rejects.toThrow("Circular dependency detected")
})
})
@@ -243,6 +262,7 @@ describe("FeedEngine", () => {
const location: FeedSource = {
id: "location",
...noActions,
async fetchContext() {
order.push("location")
return { [LocationKey]: { lat: 51.5, lng: -0.1 } }
@@ -252,6 +272,7 @@ describe("FeedEngine", () => {
const weather: FeedSource = {
id: "weather",
dependencies: ["location"],
...noActions,
async fetchContext(ctx) {
order.push("weather")
const loc = contextValue(ctx, LocationKey)
@@ -277,8 +298,14 @@ describe("FeedEngine", () => {
const { context } = await engine.refresh()
expect(contextValue(context, LocationKey)).toEqual({ lat: 51.5, lng: -0.1 })
expect(contextValue(context, WeatherKey)).toEqual({ temperature: 20, condition: "sunny" })
expect(contextValue(context, LocationKey)).toEqual({
lat: 51.5,
lng: -0.1,
})
expect(contextValue(context, WeatherKey)).toEqual({
temperature: 20,
condition: "sunny",
})
})
test("collects items from all sources", async () => {
@@ -318,6 +345,7 @@ describe("FeedEngine", () => {
test("handles missing upstream context gracefully", async () => {
const location: FeedSource = {
id: "location",
...noActions,
async fetchContext() {
return null // No location available
},
@@ -336,6 +364,7 @@ describe("FeedEngine", () => {
test("captures errors from fetchContext", async () => {
const failing: FeedSource = {
id: "failing",
...noActions,
async fetchContext() {
throw new Error("Context fetch failed")
},
@@ -353,6 +382,7 @@ describe("FeedEngine", () => {
test("captures errors from fetchItems", async () => {
const failing: FeedSource = {
id: "failing",
...noActions,
async fetchContext() {
return null
},
@@ -373,6 +403,7 @@ describe("FeedEngine", () => {
test("continues after source error", async () => {
const failing: FeedSource = {
id: "failing",
...noActions,
async fetchContext() {
throw new Error("Failed")
},
@@ -380,6 +411,7 @@ describe("FeedEngine", () => {
const working: FeedSource = {
id: "working",
...noActions,
async fetchContext() {
return null
},
@@ -423,7 +455,10 @@ describe("FeedEngine", () => {
await engine.refresh()
const context = engine.currentContext()
expect(contextValue(context, LocationKey)).toEqual({ lat: 51.5, lng: -0.1 })
expect(contextValue(context, LocationKey)).toEqual({
lat: 51.5,
lng: -0.1,
})
})
})
@@ -498,4 +533,109 @@ describe("FeedEngine", () => {
engine.stop()
})
})
describe("executeAction", () => {
test("routes action to correct source", async () => {
let receivedAction = ""
let receivedParams: unknown = {}
const source: FeedSource = {
id: "test-source",
async listActions() {
return {
"do-thing": { id: "do-thing" },
}
},
async executeAction(actionId, params) {
receivedAction = actionId
receivedParams = params
},
async fetchContext() {
return null
},
}
const engine = new FeedEngine().register(source)
await engine.executeAction("test-source", "do-thing", { key: "value" })
expect(receivedAction).toBe("do-thing")
expect(receivedParams).toEqual({ key: "value" })
})
test("throws for unknown source", async () => {
const engine = new FeedEngine()
await expect(engine.executeAction("nonexistent", "action", {})).rejects.toThrow(
"Source not found: nonexistent",
)
})
test("throws for unknown action on source", async () => {
const source: FeedSource = {
id: "test-source",
...noActions,
async fetchContext() {
return null
},
}
const engine = new FeedEngine().register(source)
await expect(engine.executeAction("test-source", "nonexistent", {})).rejects.toThrow(
'Action "nonexistent" not found on source "test-source"',
)
})
})
describe("listActions", () => {
test("returns actions for a specific source", async () => {
const source: FeedSource = {
id: "test-source",
async listActions() {
return {
"action-1": { id: "action-1" },
"action-2": { id: "action-2" },
}
},
async executeAction() {},
async fetchContext() {
return null
},
}
const engine = new FeedEngine().register(source)
const actions = await engine.listActions("test-source")
expect(Object.keys(actions)).toEqual(["action-1", "action-2"])
})
test("throws for unknown source", async () => {
const engine = new FeedEngine()
await expect(engine.listActions("nonexistent")).rejects.toThrow(
"Source not found: nonexistent",
)
})
test("throws on mismatched action ID", async () => {
const source: FeedSource = {
id: "bad-source",
async listActions() {
return {
"correct-key": { id: "wrong-id" },
}
},
async executeAction() {},
async fetchContext() {
return null
},
}
const engine = new FeedEngine().register(source)
await expect(engine.listActions("bad-source")).rejects.toThrow(
'Action ID mismatch on source "bad-source"',
)
})
})
})

45
packages/aris-core/src/feed-engine.ts
View File

@@ -1,3 +1,4 @@
import type { ActionDefinition } from "./action"
import type { Context } from "./context"
import type { FeedItem } from "./feed"
import type { FeedSource } from "./feed-source"
@@ -187,6 +188,44 @@ export class FeedEngine<TItems extends FeedItem = FeedItem> {
return this.context
}
/**
* Execute an action on a registered source.
* Validates the action exists before dispatching.
*
* In pull-only mode (before `start()` is called), the action mutates source
* state but does not automatically refresh dependents. Call `refresh()`
* after to propagate changes. In reactive mode (`start()` called), sources
* that push context updates (e.g., LocationSource) will trigger dependent
* refresh automatically.
*/
async executeAction(sourceId: string, actionId: string, params: unknown): Promise<unknown> {
const actions = await this.listActions(sourceId)
if (!(actionId in actions)) {
throw new Error(`Action "${actionId}" not found on source "${sourceId}"`)
}
return this.sources.get(sourceId)!.executeAction(actionId, params)
}
/**
* List actions available on a specific source.
* Validates that action definition IDs match their record keys.
*/
async listActions(sourceId: string): Promise<Record<string, ActionDefinition>> {
const source = this.sources.get(sourceId)
if (!source) {
throw new Error(`Source not found: ${sourceId}`)
}
const actions = await source.listActions()
for (const [key, definition] of Object.entries(actions)) {
if (key !== definition.id) {
throw new Error(
`Action ID mismatch on source "${sourceId}": key "${key}" !== definition.id "${definition.id}"`,
)
}
}
return actions
}
private ensureGraph(): SourceGraph {
if (!this.graph) {
this.graph = buildGraph(Array.from(this.sources.values()))
@@ -240,7 +279,11 @@ export class FeedEngine<TItems extends FeedItem = FeedItem> {
items.sort((a, b) => b.priority - a.priority)
this.notifySubscribers({ context: this.context, items: items as TItems[], errors })
this.notifySubscribers({
context: this.context,
items: items as TItems[],
errors,
})
}
private collectDependents(sourceId: string, graph: SourceGraph): string[] {

36
packages/aris-core/src/feed-source.test.ts
View File

@@ -1,8 +1,18 @@
import { describe, expect, test } from "bun:test"
import type { Context, ContextKey, FeedItem, FeedSource } from "./index"
import type { ActionDefinition, Context, ContextKey, FeedItem, FeedSource } from "./index"
import { contextKey, contextValue } from "./index"
import { UnknownActionError, contextKey, contextValue } from "./index"
// No-op action methods for test sources
const noActions = {
async listActions(): Promise<Record<string, ActionDefinition>> {
return {}
},
async executeAction(actionId: string): Promise<void> {
throw new UnknownActionError(actionId)
},
}
// =============================================================================
// CONTEXT KEYS
@@ -42,6 +52,7 @@ function createLocationSource(): SimulatedLocationSource {
return {
id: "location",
...noActions,
onContextUpdate(cb) {
callback = cb
@@ -70,6 +81,7 @@ function createWeatherSource(
return {
id: "weather",
dependencies: ["location"],
...noActions,
async fetchContext(context) {
const location = contextValue(context, LocationKey)
@@ -103,6 +115,7 @@ function createAlertSource(): FeedSource<AlertFeedItem> {
return {
id: "alert",
dependencies: ["weather"],
...noActions,
async fetchContext() {
return null
@@ -265,6 +278,7 @@ describe("FeedSource", () => {
const orphan: FeedSource = {
id: "orphan",
dependencies: ["nonexistent"],
...noActions,
async fetchContext() {
return null
},
@@ -279,6 +293,7 @@ describe("FeedSource", () => {
const a: FeedSource = {
id: "a",
dependencies: ["b"],
...noActions,
async fetchContext() {
return null
},
@@ -286,6 +301,7 @@ describe("FeedSource", () => {
const b: FeedSource = {
id: "b",
dependencies: ["a"],
...noActions,
async fetchContext() {
return null
},
@@ -298,6 +314,7 @@ describe("FeedSource", () => {
const a: FeedSource = {
id: "a",
dependencies: ["c"],
...noActions,
async fetchContext() {
return null
},
@@ -305,6 +322,7 @@ describe("FeedSource", () => {
const b: FeedSource = {
id: "b",
dependencies: ["a"],
...noActions,
async fetchContext() {
return null
},
@@ -312,6 +330,7 @@ describe("FeedSource", () => {
const c: FeedSource = {
id: "c",
dependencies: ["b"],
...noActions,
async fetchContext() {
return null
},
@@ -350,6 +369,7 @@ describe("FeedSource", () => {
const location: FeedSource = {
id: "location",
...noActions,
async fetchContext() {
order.push("location")
return { [LocationKey]: { lat: 51.5, lng: -0.1 } }
@@ -359,6 +379,7 @@ describe("FeedSource", () => {
const weather: FeedSource = {
id: "weather",
dependencies: ["location"],
...noActions,
async fetchContext(ctx) {
order.push("weather")
const loc = contextValue(ctx, LocationKey)
@@ -382,8 +403,14 @@ describe("FeedSource", () => {
const graph = buildGraph([location, weather])
const { context } = await refreshGraph(graph)
expect(contextValue(context, LocationKey)).toEqual({ lat: 51.5, lng: -0.1 })
expect(contextValue(context, WeatherKey)).toEqual({ temperature: 20, condition: "sunny" })
expect(contextValue(context, LocationKey)).toEqual({
lat: 51.5,
lng: -0.1,
})
expect(contextValue(context, WeatherKey)).toEqual({
temperature: 20,
condition: "sunny",
})
})
test("collects items from all sources", async () => {
@@ -422,6 +449,7 @@ describe("FeedSource", () => {
// Location source exists but hasn't been updated
const location: FeedSource = {
id: "location",
...noActions,
async fetchContext() {
// Simulate no location available
return null

68
packages/aris-core/src/feed-source.ts
View File

@@ -1,61 +1,60 @@
import type { ActionDefinition } from "./action"
import type { Context } from "./context"
import type { FeedItem } from "./feed"
/**
* Unified interface for sources that provide context and/or feed items.
* Unified interface for sources that provide context, feed items, and actions.
*
* Sources form a dependency graph - a source declares which other sources
* Sources form a dependency graph — a source declares which other sources
* it depends on, and the graph ensures dependencies are resolved before
* dependents run.
*
* A source may:
* - Provide context for other sources (implement fetchContext/onContextUpdate)
* - Produce feed items (implement fetchItems/onItemsUpdate)
* - Both
* Source IDs use reverse domain notation. Built-in sources use `aris.<name>`,
* third parties use their own domain (e.g., `com.spotify`).
*
* Every method maps to a protocol operation for remote source support:
* - `id`, `dependencies` → source/describe
* - `listActions()` → source/listActions
* - `executeAction()` → source/executeAction
* - `fetchContext()` → source/fetchContext
* - `fetchItems()` → source/fetchItems
* - `onContextUpdate()` → source/contextUpdated (notification)
* - `onItemsUpdate()` → source/itemsUpdated (notification)
*
* @example
* ```ts
* // Location source - provides context only
* const locationSource: FeedSource = {
* id: "location",
* fetchContext: async () => {
* const pos = await getCurrentPosition()
* return { location: { lat: pos.coords.latitude, lng: pos.coords.longitude } }
* },
* }
*
* // Weather source - depends on location, provides both context and items
* const weatherSource: FeedSource<WeatherFeedItem> = {
* id: "weather",
* dependencies: ["location"],
* fetchContext: async (ctx) => {
* const weather = await fetchWeather(ctx.location)
* return { weather }
* },
* fetchItems: async (ctx) => {
* return createWeatherFeedItems(ctx.weather)
* },
* }
*
* // TFL source - no context to provide
* const tflSource: FeedSource<TflFeedItem> = {
* id: "tfl",
* fetchContext: async () => null,
* fetchItems: async (ctx) => { ... },
* id: "aris.location",
* async listActions() { return { "update-location": { id: "update-location" } } },
* async executeAction(actionId) { throw new UnknownActionError(actionId) },
* async fetchContext() { ... },
* }
* ```
*/
export interface FeedSource<TItem extends FeedItem = FeedItem> {
/** Unique identifier for this source */
/** Unique identifier for this source in reverse-domain format */
readonly id: string
/** IDs of sources this source depends on */
readonly dependencies?: readonly string[]
/**
* List actions this source supports. Empty record if none.
* Maps to: source/listActions
*/
listActions(): Promise<Record<string, ActionDefinition>>
/**
* Execute an action by ID. Throws on unknown action or invalid input.
* Maps to: source/executeAction
*/
executeAction(actionId: string, params: unknown): Promise<unknown>
/**
* Subscribe to reactive context updates.
* Called when the source can push context changes proactively.
* Returns cleanup function.
* Maps to: source/contextUpdated (notification, source → host)
*/
onContextUpdate?(
callback: (update: Partial<Context>) => void,
@@ -66,6 +65,7 @@ export interface FeedSource<TItem extends FeedItem = FeedItem> {
* Fetch context on-demand.
* Called during manual refresh or initial load.
* Return null if this source cannot provide context.
* Maps to: source/fetchContext
*/
fetchContext(context: Context): Promise<Partial<Context> | null>
@@ -73,12 +73,14 @@ export interface FeedSource<TItem extends FeedItem = FeedItem> {
* Subscribe to reactive feed item updates.
* Called when the source can push item changes proactively.
* Returns cleanup function.
* Maps to: source/itemsUpdated (notification, source → host)
*/
onItemsUpdate?(callback: (items: TItem[]) => void, getContext: () => Context): () => void
/**
* Fetch feed items on-demand.
* Called during manual refresh or when dependencies update.
* Maps to: source/fetchItems
*/
fetchItems?(context: Context): Promise<TItem[]>
}

4
packages/aris-core/src/index.ts
View File

@@ -2,6 +2,10 @@
export type { Context, ContextKey } from "./context"
export { contextKey, contextValue } from "./context"
// Actions
export type { ActionDefinition } from "./action"
export { UnknownActionError } from "./action"
// Feed
export type { FeedItem } from "./feed"

20
packages/aris-data-source-weatherkit/src/data-source.test.ts
View File

@@ -26,14 +26,18 @@ const createMockContext = (location?: { lat: number; lng: number }): Context =>
describe("WeatherKitDataSource", () => {
test("returns empty array when location is missing", async () => {
const dataSource = new WeatherKitDataSource({ credentials: mockCredentials })
const dataSource = new WeatherKitDataSource({
credentials: mockCredentials,
})
const items = await dataSource.query(createMockContext())
expect(items).toEqual([])
})
test("type is weather-current", () => {
const dataSource = new WeatherKitDataSource({ credentials: mockCredentials })
const dataSource = new WeatherKitDataSource({
credentials: mockCredentials,
})
expect(dataSource.type).toBe(WeatherFeedItemType.current)
})
@@ -100,7 +104,9 @@ describe("WeatherKitDataSource with fixture", () => {
})
test("default limits are applied", () => {
const dataSource = new WeatherKitDataSource({ credentials: mockCredentials })
const dataSource = new WeatherKitDataSource({
credentials: mockCredentials,
})
expect(dataSource["hourlyLimit"]).toBe(12)
expect(dataSource["dailyLimit"]).toBe(7)
@@ -163,8 +169,12 @@ describe("query() with mocked client", () => {
const dataSource = new WeatherKitDataSource({ client: mockClient })
const context = createMockContext({ lat: 37.7749, lng: -122.4194 })
const metricItems = await dataSource.query(context, { units: Units.metric })
const imperialItems = await dataSource.query(context, { units: Units.imperial })
const metricItems = await dataSource.query(context, {
units: Units.metric,
})
const imperialItems = await dataSource.query(context, {
units: Units.imperial,
})
const metricCurrent = metricItems.find((i) => i.type === WeatherFeedItemType.current)
const imperialCurrent = imperialItems.find((i) => i.type === WeatherFeedItemType.current)

21
packages/aris-source-apple-calendar/src/calendar-source.test.ts
View File

@@ -78,7 +78,7 @@ class MockDAVClient implements CalendarDAVClient {
describe("CalendarSource", () => {
test("has correct id", () => {
const source = new CalendarSource(new NullCredentialProvider(), "user-1")
expect(source.id).toBe("apple-calendar")
expect(source.id).toBe("aris.apple-calendar")
})
test("returns empty array when credentials are null", async () => {
@@ -121,7 +121,10 @@ describe("CalendarSource", () => {
const objects: Record<string, CalendarDAVObject[]> = {
"/cal/work": [{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") }],
"/cal/personal": [
{ url: "/cal/personal/event2.ics", data: loadFixture("all-day-event.ics") },
{
url: "/cal/personal/event2.ics",
data: loadFixture("all-day-event.ics"),
},
],
}
const client = new MockDAVClient(
@@ -206,7 +209,12 @@ describe("CalendarSource", () => {
test("handles calendar with non-string displayName", async () => {
const objects: Record<string, CalendarDAVObject[]> = {
"/cal/weird": [{ url: "/cal/weird/event1.ics", data: loadFixture("minimal-event.ics") }],
"/cal/weird": [
{
url: "/cal/weird/event1.ics",
data: loadFixture("minimal-event.ics"),
},
],
}
const client = new MockDAVClient(
[{ url: "/cal/weird", displayName: { _cdata: "Weird Calendar" } }],
@@ -222,7 +230,12 @@ describe("CalendarSource", () => {
test("handles recurring events with exceptions", async () => {
const objects: Record<string, CalendarDAVObject[]> = {
"/cal/work": [{ url: "/cal/work/recurring.ics", data: loadFixture("recurring-event.ics") }],
"/cal/work": [
{
url: "/cal/work/recurring.ics",
data: loadFixture("recurring-event.ics"),
},
],
}
const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
const source = new CalendarSource(new MockCredentialProvider(), "user-1", {

13
packages/aris-source-apple-calendar/src/calendar-source.ts
View File

@@ -1,4 +1,5 @@
import type { Context, FeedSource } from "@aris/core"
import type { ActionDefinition, Context, FeedSource } from "@aris/core"
import { UnknownActionError } from "@aris/core"
import { DAVClient } from "tsdav"
@@ -37,7 +38,7 @@ const DEFAULT_LOOK_AHEAD_DAYS = 0
* ```
*/
export class CalendarSource implements FeedSource<CalendarFeedItem> {
readonly id = "apple-calendar"
readonly id = "aris.apple-calendar"
private readonly credentialProvider: CalendarCredentialProvider
private readonly userId: string
@@ -58,6 +59,14 @@ export class CalendarSource implements FeedSource<CalendarFeedItem> {
this.injectedClient = options?.davClient ?? null
}
async listActions(): Promise<Record<string, ActionDefinition>> {
return {}
}
async executeAction(actionId: string): Promise<void> {
throw new UnknownActionError(actionId)
}
async fetchContext(context: Context): Promise<Partial<Context> | null> {
const events = await this.fetchEvents(context)
if (events.length === 0) {

10
packages/aris-source-google-calendar/src/google-calendar-source.test.ts
View File

@@ -45,13 +45,15 @@ describe("GoogleCalendarSource", () => {
describe("constructor", () => {
test("has correct id", () => {
const source = new GoogleCalendarSource({ client: defaultMockClient() })
expect(source.id).toBe("google-calendar")
expect(source.id).toBe("aris.google-calendar")
})
})
describe("fetchItems", () => {
test("returns empty array when no events", async () => {
const source = new GoogleCalendarSource({ client: createMockClient({ primary: [] }) })
const source = new GoogleCalendarSource({
client: createMockClient({ primary: [] }),
})
const items = await source.fetchItems(createContext())
expect(items).toEqual([])
})
@@ -198,7 +200,9 @@ describe("GoogleCalendarSource", () => {
describe("fetchContext", () => {
test("returns null when no events", async () => {
const source = new GoogleCalendarSource({ client: createMockClient({ primary: [] }) })
const source = new GoogleCalendarSource({
client: createMockClient({ primary: [] }),
})
const result = await source.fetchContext(createContext())
expect(result).toBeNull()
})

14
packages/aris-source-google-calendar/src/google-calendar-source.ts
View File

@@ -1,4 +1,6 @@
import type { Context, FeedSource } from "@aris/core"
import type { ActionDefinition, Context, FeedSource } from "@aris/core"
import { UnknownActionError } from "@aris/core"
import type {
ApiCalendarEvent,
@@ -63,7 +65,7 @@ const PRIORITY_ALL_DAY = 0.4
* ```
*/
export class GoogleCalendarSource implements FeedSource<CalendarFeedItem> {
readonly id = "google-calendar"
readonly id = "aris.google-calendar"
private readonly client: GoogleCalendarClient
private readonly calendarIds: string[] | undefined
@@ -75,6 +77,14 @@ export class GoogleCalendarSource implements FeedSource<CalendarFeedItem> {
this.lookaheadHours = options.lookaheadHours ?? DEFAULT_LOOKAHEAD_HOURS
}
async listActions(): Promise<Record<string, ActionDefinition>> {
return {}
}
async executeAction(actionId: string): Promise<void> {
throw new UnknownActionError(actionId)
}
async fetchContext(context: Context): Promise<Partial<Context> | null> {
const events = await this.fetchAllEvents(context.time)

3
packages/aris-source-location/package.json
View File

@@ -8,6 +8,7 @@
"test": "bun test src/"
},
"dependencies": {
"@aris/core": "workspace:*"
"@aris/core": "workspace:*",
"arktype": "^2.1.0"
}
}

8
packages/aris-source-location/src/index.ts
View File

@@ -1,6 +1,2 @@
export {
LocationSource,
LocationKey,
type Location,
type LocationSourceOptions,
} from "./location-source.ts"
export { LocationSource, LocationKey } from "./location-source.ts"
export { Location, type LocationSourceOptions } from "./types.ts"

38
packages/aris-source-location/src/location-source.test.ts
View File

@@ -16,7 +16,7 @@ describe("LocationSource", () => {
describe("FeedSource interface", () => {
test("has correct id", () => {
const source = new LocationSource()
expect(source.id).toBe("location")
expect(source.id).toBe("aris.location")
})
test("fetchItems always returns empty array", async () => {
@@ -147,4 +147,40 @@ describe("LocationSource", () => {
expect(listener2).toHaveBeenCalledTimes(1)
})
})
describe("actions", () => {
test("listActions returns update-location action", async () => {
const source = new LocationSource()
const actions = await source.listActions()
expect(actions["update-location"]).toBeDefined()
expect(actions["update-location"]!.id).toBe("update-location")
expect(actions["update-location"]!.input).toBeDefined()
})
test("executeAction update-location pushes location", async () => {
const source = new LocationSource()
expect(source.lastLocation).toBeNull()
const location = createLocation({ lat: 40.7128, lng: -74.006 })
await source.executeAction("update-location", location)
expect(source.lastLocation).toEqual(location)
})
test("executeAction throws on invalid input", async () => {
const source = new LocationSource()
await expect(
source.executeAction("update-location", { lat: "not a number" }),
).rejects.toThrow()
})
test("executeAction throws for unknown action", async () => {
const source = new LocationSource()
await expect(source.executeAction("nonexistent", {})).rejects.toThrow("Unknown action")
})
})
})

48
packages/aris-source-location/src/location-source.ts
View File

@@ -1,22 +1,9 @@
import type { Context, FeedSource } from "@aris/core"
import type { ActionDefinition, Context, FeedSource } from "@aris/core"
import { contextKey, type ContextKey } from "@aris/core"
import { UnknownActionError, contextKey, type ContextKey } from "@aris/core"
import { type } from "arktype"
/**
* Geographic coordinates with accuracy and timestamp.
*/
export interface Location {
lat: number
lng: number
/** Accuracy in meters */
accuracy: number
timestamp: Date
}
export interface LocationSourceOptions {
/** Number of locations to retain in history. Defaults to 1. */
historySize?: number
}
import { Location, type LocationSourceOptions } from "./types.ts"
export const LocationKey: ContextKey<Location> = contextKey("location")
@@ -29,7 +16,7 @@ export const LocationKey: ContextKey<Location> = contextKey("location")
* Does not produce feed items - always returns empty array from `fetchItems`.
*/
export class LocationSource implements FeedSource {
readonly id = "location"
readonly id = "aris.location"
private readonly historySize: number
private locations: Location[] = []
@@ -39,6 +26,31 @@ export class LocationSource implements FeedSource {
this.historySize = options.historySize ?? 1
}
async listActions(): Promise<Record<string, ActionDefinition>> {
return {
"update-location": {
id: "update-location",
description: "Push a new location update",
input: Location,
},
}
}
async executeAction(actionId: string, params: unknown): Promise<void> {
switch (actionId) {
case "update-location": {
const result = Location(params)
if (result instanceof type.errors) {
throw new Error(result.summary)
}
this.pushLocation(result)
return
}
default:
throw new UnknownActionError(actionId)
}
}
/**
* Push a new location update. Notifies all context listeners.
*/

17
packages/aris-source-location/src/types.ts Normal file
View File

@@ -0,0 +1,17 @@
import { type } from "arktype"
/** Geographic coordinates with accuracy and timestamp. */
export const Location = type({
lat: "number",
lng: "number",
/** Accuracy in meters */
accuracy: "number",
timestamp: "Date",
})
export type Location = typeof Location.infer
export interface LocationSourceOptions {
/** Number of locations to retain in history. Defaults to 1. */
historySize?: number
}

2
packages/aris-source-tfl/src/tfl-api.ts
View File

@@ -142,7 +142,7 @@ export class TflApi {
// Schemas
const lineId = type(
export const lineId = type(
"'bakerloo' | 'central' | 'circle' | 'district' | 'hammersmith-city' | 'jubilee' | 'metropolitan' | 'northern' | 'piccadilly' | 'victoria' | 'waterloo-city' | 'lioness' | 'mildmay' | 'windrush' | 'weaver' | 'suffragette' | 'liberty' | 'elizabeth'",
)

93
packages/aris-source-tfl/src/tfl-source.test.ts
View File

@@ -94,12 +94,12 @@ describe("TflSource", () => {
describe("interface", () => {
test("has correct id", () => {
const source = new TflSource({ client: api })
expect(source.id).toBe("tfl")
expect(source.id).toBe("aris.tfl")
})
test("depends on location", () => {
const source = new TflSource({ client: api })
expect(source.dependencies).toEqual(["location"])
expect(source.dependencies).toEqual(["aris.location"])
})
test("implements fetchItems", () => {
@@ -122,7 +122,12 @@ describe("TflSource", () => {
severity: "minor-delays",
description: "Delays",
},
{ lineId: "central", lineName: "Central", severity: "closure", description: "Closed" },
{
lineId: "central",
lineName: "Central",
severity: "closure",
description: "Closed",
},
]
return lines ? all.filter((s) => lines.includes(s.lineId)) : all
},
@@ -144,7 +149,10 @@ describe("TflSource", () => {
})
test("DEFAULT_LINES_OF_INTEREST restores all lines", async () => {
const source = new TflSource({ client: lineFilteringApi, lines: ["northern"] })
const source = new TflSource({
client: lineFilteringApi,
lines: ["northern"],
})
const filtered = await source.fetchItems(createContext())
expect(filtered.length).toBe(1)
@@ -164,7 +172,12 @@ describe("TflSource", () => {
test("feed items have correct base structure", async () => {
const source = new TflSource({ client: api })
const location: Location = { lat: 51.5074, lng: -0.1278, accuracy: 10, timestamp: new Date() }
const location: Location = {
lat: 51.5074,
lng: -0.1278,
accuracy: 10,
timestamp: new Date(),
}
const items = await source.fetchItems(createContext(location))
for (const item of items) {
@@ -178,7 +191,12 @@ describe("TflSource", () => {
test("feed items have correct data structure", async () => {
const source = new TflSource({ client: api })
const location: Location = { lat: 51.5074, lng: -0.1278, accuracy: 10, timestamp: new Date() }
const location: Location = {
lat: 51.5074,
lng: -0.1278,
accuracy: 10,
timestamp: new Date(),
}
const items = await source.fetchItems(createContext(location))
for (const item of items) {
@@ -230,7 +248,12 @@ describe("TflSource", () => {
test("closestStationDistance is number when location provided", async () => {
const source = new TflSource({ client: api })
const location: Location = { lat: 51.5074, lng: -0.1278, accuracy: 10, timestamp: new Date() }
const location: Location = {
lat: 51.5074,
lng: -0.1278,
accuracy: 10,
timestamp: new Date(),
}
const items = await source.fetchItems(createContext(location))
for (const item of items) {
@@ -248,6 +271,62 @@ describe("TflSource", () => {
}
})
})
describe("actions", () => {
test("listActions returns set-lines-of-interest", async () => {
const source = new TflSource({ client: api })
const actions = await source.listActions()
expect(actions["set-lines-of-interest"]).toBeDefined()
expect(actions["set-lines-of-interest"]!.id).toBe("set-lines-of-interest")
})
test("executeAction set-lines-of-interest updates lines", async () => {
const lineFilteringApi: ITflApi = {
async fetchLineStatuses(lines?: TflLineId[]): Promise<TflLineStatus[]> {
const all: TflLineStatus[] = [
{
lineId: "northern",
lineName: "Northern",
severity: "minor-delays",
description: "Delays",
},
{
lineId: "central",
lineName: "Central",
severity: "closure",
description: "Closed",
},
]
return lines ? all.filter((s) => lines.includes(s.lineId)) : all
},
async fetchStations(): Promise<StationLocation[]> {
return []
},
}
const source = new TflSource({ client: lineFilteringApi })
await source.executeAction("set-lines-of-interest", ["northern"])
const items = await source.fetchItems(createContext())
expect(items.length).toBe(1)
expect(items[0]!.data.line).toBe("northern")
})
test("executeAction throws on invalid input", async () => {
const source = new TflSource({ client: api })
await expect(
source.executeAction("set-lines-of-interest", "not-an-array"),
).rejects.toThrow()
})
test("executeAction throws for unknown action", async () => {
const source = new TflSource({ client: api })
await expect(source.executeAction("nonexistent", {})).rejects.toThrow("Unknown action")
})
})
})
describe("TfL Fixture Data Shape", () => {

38
packages/aris-source-tfl/src/tfl-source.ts
View File

@@ -1,7 +1,8 @@
import type { Context, FeedSource } from "@aris/core"
import type { ActionDefinition, Context, FeedSource } from "@aris/core"
import { contextValue } from "@aris/core"
import { UnknownActionError, contextValue } from "@aris/core"
import { LocationKey } from "@aris/source-location"
import { type } from "arktype"
import type {
ITflApi,
@@ -13,7 +14,9 @@ import type {
TflSourceOptions,
} from "./types.ts"
import { TflApi } from "./tfl-api.ts"
import { TflApi, lineId } from "./tfl-api.ts"
const setLinesInput = lineId.array()
const SEVERITY_PRIORITY: Record<TflAlertSeverity, number> = {
closure: 1.0,
@@ -63,8 +66,8 @@ export class TflSource implements FeedSource<TflAlertFeedItem> {
"elizabeth",
]
readonly id = "tfl"
readonly dependencies = ["location"]
readonly id = "aris.tfl"
readonly dependencies = ["aris.location"]
private readonly client: ITflApi
private lines: TflLineId[]
@@ -77,6 +80,31 @@ export class TflSource implements FeedSource<TflAlertFeedItem> {
this.lines = options.lines ?? [...TflSource.DEFAULT_LINES_OF_INTEREST]
}
async listActions(): Promise<Record<string, ActionDefinition>> {
return {
"set-lines-of-interest": {
id: "set-lines-of-interest",
description: "Update the set of monitored TfL lines",
input: setLinesInput,
},
}
}
async executeAction(actionId: string, params: unknown): Promise<void> {
switch (actionId) {
case "set-lines-of-interest": {
const result = setLinesInput(params)
if (result instanceof type.errors) {
throw new Error(result.summary)
}
this.setLinesOfInterest(result)
return
}
default:
throw new UnknownActionError(actionId)
}
}
async fetchContext(): Promise<null> {
return null
}

9
packages/aris-source-weatherkit/src/weather-source.test.ts
View File

@@ -34,12 +34,12 @@ describe("WeatherSource", () => {
describe("properties", () => {
test("has correct id", () => {
const source = new WeatherSource({ credentials: mockCredentials })
expect(source.id).toBe("weather")
expect(source.id).toBe("aris.weather")
})
test("depends on location", () => {
const source = new WeatherSource({ credentials: mockCredentials })
expect(source.dependencies).toEqual(["location"])
expect(source.dependencies).toEqual(["aris.location"])
})
test("throws error if neither client nor credentials provided", () => {
@@ -78,7 +78,10 @@ describe("WeatherSource", () => {
})
test("converts temperature to imperial", async () => {
const source = new WeatherSource({ client: mockClient, units: Units.imperial })
const source = new WeatherSource({
client: mockClient,
units: Units.imperial,
})
const context = createMockContext({ lat: 37.7749, lng: -122.4194 })
const result = await source.fetchContext(context)

16
packages/aris-source-weatherkit/src/weather-source.ts
View File

@@ -1,6 +1,6 @@
import type { Context, FeedSource } from "@aris/core"
import type { ActionDefinition, Context, FeedSource } from "@aris/core"
import { contextValue } from "@aris/core"
import { UnknownActionError, contextValue } from "@aris/core"
import { LocationKey } from "@aris/source-location"
import { WeatherFeedItemType, type WeatherFeedItem } from "./feed-items"
@@ -93,8 +93,8 @@ const MODERATE_CONDITIONS = new Set<ConditionCode>([
* ```
*/
export class WeatherSource implements FeedSource<WeatherFeedItem> {
readonly id = "weather"
readonly dependencies = ["location"]
readonly id = "aris.weather"
readonly dependencies = ["aris.location"]
private readonly client: WeatherKitClient
private readonly hourlyLimit: number
@@ -111,6 +111,14 @@ export class WeatherSource implements FeedSource<WeatherFeedItem> {
this.units = options.units ?? Units.metric
}
async listActions(): Promise<Record<string, ActionDefinition>> {
return {}
}
async executeAction(actionId: string): Promise<void> {
throw new UnknownActionError(actionId)
}
async fetchContext(context: Context): Promise<Partial<Context> | null> {
const location = contextValue(context, LocationKey)
if (!location) {