@tinycloud/sdk-services 2.0.4 → 2.1.0-beta.1

package/dist/index.js

@@ -280,6 +280,7 @@ var ServiceContext = class {
     this._eventHandlers = /* @__PURE__ */ new Map();
     this._abortController = new AbortController();
     this._invoke = config.invoke;
+    this._invokeAny = config.invokeAny;
     this._fetch = config.fetch ?? globalThis.fetch.bind(globalThis);
     this._hosts = config.hosts;
     this._session = config.session ?? null;
@@ -324,6 +325,12 @@ var ServiceContext = class {
   get invoke() {
     return this._invoke;
   }
+  /**
+   * Get the multi-resource invoke function when available.
+   */
+  get invokeAny() {
+    return this._invokeAny;
+  }
   /**
    * Get the fetch function for HTTP requests.
    */
@@ -1910,6 +1917,683 @@ var DuckDbService = class extends BaseService {
 };
 DuckDbService.serviceName = "duckdb";
 
+// src/hooks/HooksService.ts
+var AsyncQueue = class {
+  constructor() {
+    this.values = [];
+    this.waiters = [];
+    this.closed = false;
+  }
+  [Symbol.asyncIterator]() {
+    return this;
+  }
+  push(value) {
+    if (this.closed) {
+      return;
+    }
+    const waiter = this.waiters.shift();
+    if (waiter) {
+      waiter({ value, done: false });
+      return;
+    }
+    this.values.push(value);
+  }
+  close() {
+    if (this.closed) {
+      return;
+    }
+    this.closed = true;
+    while (this.waiters.length > 0) {
+      const waiter = this.waiters.shift();
+      waiter?.({ value: void 0, done: true });
+    }
+  }
+  next() {
+    if (this.values.length > 0) {
+      const value = this.values.shift();
+      return Promise.resolve({ value, done: false });
+    }
+    if (this.closed) {
+      return Promise.resolve({ value: void 0, done: true });
+    }
+    return new Promise((resolve) => {
+      this.waiters.push(resolve);
+    });
+  }
+};
+var HooksService = class extends BaseService {
+  constructor(config = {}) {
+    super();
+    this._subscribers = /* @__PURE__ */ new Set();
+    this._refreshChain = Promise.resolve();
+    this._activeSignature = "";
+    this._config = config;
+  }
+  get config() {
+    return this._config;
+  }
+  get host() {
+    return this._config.host ?? this.context.hosts[0];
+  }
+  async *subscribe(subscriptions, options = {}) {
+    if (!this.requireAuth()) {
+      throw new Error("Authentication required for hooks subscription");
+    }
+    if (subscriptions.length === 0) {
+      throw new Error("At least one hook subscription is required");
+    }
+    const normalized = subscriptions.map(normalizeSubscription);
+    const subscriber = {
+      requested: normalized,
+      ttlSeconds: options.ttlSeconds,
+      queue: new AsyncQueue()
+    };
+    this._subscribers.add(subscriber);
+    const abortHandler = () => {
+      this._subscribers.delete(subscriber);
+      subscriber.queue.close();
+      void this.scheduleSharedStreamRefresh();
+    };
+    if (options.signal) {
+      if (options.signal.aborted) {
+        abortHandler();
+      } else {
+        options.signal.addEventListener("abort", abortHandler, { once: true });
+      }
+    }
+    void this.scheduleSharedStreamRefresh();
+    try {
+      for await (const event of subscriber.queue) {
+        yield event;
+      }
+    } finally {
+      if (options.signal) {
+        options.signal.removeEventListener("abort", abortHandler);
+      }
+      abortHandler();
+    }
+  }
+  async register(webhook) {
+    if (!this.requireAuth()) {
+      return err(authRequiredError("hooks"));
+    }
+    if (typeof webhook.secret !== "string" || webhook.secret.trim().length === 0) {
+      return err(
+        serviceError(
+          ErrorCodes.INVALID_INPUT,
+          "Webhook secret is required",
+          "hooks",
+          { meta: { field: "secret" } }
+        )
+      );
+    }
+    try {
+      const response = await this.context.fetch(`${this.host}/hooks/webhooks`, {
+        method: "POST",
+        headers: {
+          ...serviceHeadersToRecord(
+            this.createHookHeaders(
+              "tinycloud.hooks/register",
+              buildScopePath(webhook.service, webhook.pathPrefix)
+            )
+          ),
+          "content-type": "application/json"
+        },
+        body: JSON.stringify({
+          space: webhook.space,
+          service: webhook.service,
+          pathPrefix: normalizePathPrefix(webhook.pathPrefix),
+          abilities: webhook.abilities ?? [],
+          callbackUrl: webhook.callbackUrl,
+          secret: webhook.secret
+        })
+      });
+      if (!response.ok) {
+        return err(
+          await responseError("hooks", "failed to register webhook", response)
+        );
+      }
+      const data = normalizeWebhookRecord(await response.json());
+      if (!data) {
+        return err(
+          wrapError(
+            "hooks",
+            new Error("Webhook registration response did not include a record")
+          )
+        );
+      }
+      return ok(data);
+    } catch (error) {
+      return err(wrapError("hooks", error));
+    }
+  }
+  async list(options = {}) {
+    if (!this.requireAuth()) {
+      return err(authRequiredError("hooks"));
+    }
+    try {
+      const query = new URLSearchParams();
+      if (options.space) {
+        query.set("space", options.space);
+      }
+      if (options.service) {
+        query.set("service", options.service);
+      }
+      if (options.pathPrefix) {
+        const normalizedPrefix = normalizePathPrefix(options.pathPrefix);
+        if (normalizedPrefix) {
+          query.set("prefix", normalizedPrefix);
+        }
+      }
+      const response = await this.context.fetch(
+        `${this.host}/hooks/webhooks${query.size > 0 ? `?${query.toString()}` : ""}`,
+        {
+          method: "GET",
+          headers: serviceHeadersToRecord(
+            this.createHookHeaders(
+              "tinycloud.hooks/list",
+              options.service ? buildScopePath(options.service, options.pathPrefix) : "webhooks"
+            )
+          )
+        }
+      );
+      if (!response.ok) {
+        return err(
+          await responseError("hooks", "failed to list webhooks", response)
+        );
+      }
+      const payload = await response.json();
+      const records = normalizeWebhookRecordList(payload);
+      if (!records) {
+        return err(
+          wrapError(
+            "hooks",
+            new Error("Webhook list response did not include records")
+          )
+        );
+      }
+      return ok(records);
+    } catch (error) {
+      return err(wrapError("hooks", error));
+    }
+  }
+  async unregister(id, options = {}) {
+    if (!this.requireAuth()) {
+      return err(authRequiredError("hooks"));
+    }
+    try {
+      const response = await this.context.fetch(
+        `${this.host}/hooks/webhooks/${encodeURIComponent(id)}`,
+        {
+          method: "DELETE",
+          headers: serviceHeadersToRecord(
+            this.createHookHeaders(
+              "tinycloud.hooks/unregister",
+              options.target ? buildScopePath(
+                options.target.service,
+                options.target.pathPrefix
+              ) : `webhooks/${id}`
+            )
+          )
+        }
+      );
+      if (!response.ok) {
+        return err(
+          await responseError(
+            "hooks",
+            "failed to unregister webhook",
+            response
+          )
+        );
+      }
+      return ok(void 0);
+    } catch (error) {
+      return err(wrapError("hooks", error));
+    }
+  }
+  async scheduleSharedStreamRefresh() {
+    this._refreshChain = this._refreshChain.then(() => this.refreshSharedStream()).catch(() => void 0);
+    await this._refreshChain;
+  }
+  async refreshSharedStream() {
+    if (!this.requireAuth() || this._subscribers.size === 0) {
+      this.abortSharedStream();
+      this._activeSignature = "";
+      return;
+    }
+    const state = this.collectSharedStreamState();
+    if (state.signature !== this._activeSignature) {
+      this._activeSignature = state.signature;
+      this.abortSharedStream();
+    }
+    if (!this._sharedStreamTask) {
+      this._sharedStreamTask = this.runSharedStream(state).catch((error) => {
+        if (!isAbortError(error)) {
+          throw error;
+        }
+      }).finally(() => {
+        this._sharedStreamTask = void 0;
+        this._sharedStreamAbort = void 0;
+        if (this._subscribers.size > 0) {
+          void this.scheduleSharedStreamRefresh();
+        }
+      });
+    }
+  }
+  collectSharedStreamState() {
+    const merged = /* @__PURE__ */ new Map();
+    const ttlCandidates = [];
+    for (const subscriber of this._subscribers) {
+      if (typeof subscriber.ttlSeconds === "number") {
+        ttlCandidates.push(subscriber.ttlSeconds);
+      }
+      for (const subscription of subscriber.requested) {
+        merged.set(subscriptionSignature(subscription), subscription);
+      }
+    }
+    const subscriptions = [...merged.values()].sort(
+      (left, right) => subscriptionSignature(left).localeCompare(subscriptionSignature(right))
+    );
+    const ttlSeconds = ttlCandidates.length > 0 ? Math.min(...ttlCandidates) : void 0;
+    const signature = JSON.stringify({
+      subscriptions: subscriptions.map(subscriptionSignature),
+      ttlSeconds
+    });
+    return {
+      subscriptions,
+      ttlSeconds,
+      signature
+    };
+  }
+  async runSharedStream(state) {
+    const abortController = new AbortController();
+    this._sharedStreamAbort = abortController;
+    try {
+      const host = this._config.host ?? this.context.hosts[0];
+      const ticketResponse = await this.mintHookTicket(
+        state.subscriptions,
+        state.ttlSeconds,
+        abortController.signal
+      );
+      const streamResponse = await this.openHookStream(
+        host,
+        ticketResponse.ticket,
+        abortController.signal
+      );
+      for await (const message of parseSseStream(
+        streamResponse.body,
+        abortController.signal
+      )) {
+        if (!message.data) {
+          continue;
+        }
+        const event = parseHookEvent(message);
+        for (const subscriber of this._subscribers) {
+          if (matchesAnySubscription(event, subscriber.requested)) {
+            subscriber.queue.push(event);
+          }
+        }
+      }
+    } finally {
+      if (this._sharedStreamAbort === abortController) {
+        this._sharedStreamAbort = void 0;
+      }
+    }
+  }
+  abortSharedStream() {
+    this._sharedStreamAbort?.abort();
+  }
+  createHookHeaders(action, path) {
+    return this.context.invoke(this.session, "hooks", path, action);
+  }
+  async mintHookTicket(subscriptions, ttlSeconds, signal) {
+    const host = this._config.host ?? this.context.hosts[0];
+    const headers = this.createInvokeHeaders(subscriptions);
+    const ticketResponse = await this.context.fetch(`${host}/hooks/tickets`, {
+      method: "POST",
+      headers: {
+        ...serviceHeadersToRecord(headers),
+        "content-type": "application/json"
+      },
+      body: JSON.stringify({
+        subscriptions,
+        ttlSeconds
+      }),
+      signal
+    });
+    if (!ticketResponse.ok) {
+      throw await responseError(
+        "hooks",
+        "failed to mint hook ticket",
+        ticketResponse
+      );
+    }
+    const ticketJson = await ticketResponse.json();
+    if (!ticketJson?.ticket) {
+      throw new Error("Hook ticket response did not include a ticket");
+    }
+    return ticketJson;
+  }
+  async openHookStream(host, ticket, signal) {
+    const streamResponse = await this.context.fetch(
+      `${host}/hooks/events?ticket=${encodeURIComponent(ticket)}`,
+      {
+        method: "GET",
+        headers: { accept: "text/event-stream" },
+        signal
+      }
+    );
+    if (!streamResponse.ok) {
+      throw await responseError(
+        "hooks",
+        "failed to open hook stream",
+        streamResponse
+      );
+    }
+    return streamResponse;
+  }
+  createInvokeHeaders(subscriptions) {
+    const entries = subscriptions.map((subscription) => ({
+      spaceId: subscription.space,
+      service: "hooks",
+      path: subscription.pathPrefix ? `${subscription.service}/${subscription.pathPrefix}` : subscription.service,
+      action: "tinycloud.hooks/subscribe"
+    }));
+    if (this.context.invokeAny) {
+      return this.context.invokeAny(this.session, entries);
+    }
+    if (entries.length === 1) {
+      const entry = entries[0];
+      return this.context.invoke(
+        this.session,
+        entry.service,
+        entry.path,
+        entry.action
+      );
+    }
+    throw new Error(
+      "This SDK runtime does not support multi-scope hook invocations"
+    );
+  }
+};
+HooksService.serviceName = "hooks";
+function buildScopePath(service, pathPrefix) {
+  const normalized = normalizePathPrefix(pathPrefix);
+  return normalized ? `${service}/${normalized}` : service;
+}
+function normalizeSubscription(subscription) {
+  return {
+    ...subscription,
+    pathPrefix: normalizePathPrefix(subscription.pathPrefix),
+    abilities: subscription.abilities ?? []
+  };
+}
+function subscriptionSignature(subscription) {
+  return JSON.stringify({
+    space: subscription.space,
+    service: subscription.service,
+    pathPrefix: subscription.pathPrefix ?? "",
+    abilities: [...subscription.abilities ?? []].sort()
+  });
+}
+function matchesAnySubscription(event, subscriptions) {
+  return subscriptions.some(
+    (subscription) => matchesSubscription(event, subscription)
+  );
+}
+function matchesSubscription(event, subscription) {
+  if (event.space !== subscription.space) {
+    return false;
+  }
+  if (event.service !== subscription.service) {
+    return false;
+  }
+  if (subscription.pathPrefix) {
+    const prefix = subscription.pathPrefix.endsWith("/") ? subscription.pathPrefix : `${subscription.pathPrefix}/`;
+    if (event.path && event.path !== subscription.pathPrefix && !event.path.startsWith(prefix)) {
+      return false;
+    }
+  }
+  const abilities = subscription.abilities ?? [];
+  if (abilities.length > 0 && !abilities.includes(event.ability)) {
+    return false;
+  }
+  return true;
+}
+function normalizePathPrefix(pathPrefix) {
+  if (!pathPrefix) {
+    return void 0;
+  }
+  const trimmed = pathPrefix.replace(/^\/+|\/+$/g, "");
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+function serviceHeadersToRecord(headers) {
+  if (Array.isArray(headers)) {
+    return Object.fromEntries(headers);
+  }
+  return { ...headers };
+}
+async function responseError(service, message, response) {
+  let detail = response.statusText;
+  try {
+    const text = await response.text();
+    if (text) {
+      detail = text;
+    }
+  } catch {
+  }
+  return wrapError(
+    service,
+    new Error(`${message}: ${response.status} ${detail}`)
+  );
+}
+function isAbortError(error) {
+  return error instanceof DOMException && error.name === "AbortError";
+}
+async function* parseSseStream(body, signal) {
+  if (!body) {
+    throw new Error("Hook stream response does not expose a readable body");
+  }
+  const decoder = new TextDecoder();
+  let buffer = "";
+  for await (const chunk of readBodyChunks(body, signal)) {
+    buffer += decoder.decode(chunk, { stream: true }).replace(/\r\n/g, "\n");
+    let separatorIndex = buffer.indexOf("\n\n");
+    while (separatorIndex >= 0) {
+      const rawEvent = buffer.slice(0, separatorIndex);
+      buffer = buffer.slice(separatorIndex + 2);
+      const parsed = parseSseEvent(rawEvent);
+      if (parsed) {
+        yield parsed;
+      }
+      separatorIndex = buffer.indexOf("\n\n");
+    }
+  }
+  buffer += decoder.decode();
+  const trailing = parseSseEvent(buffer.trim());
+  if (trailing) {
+    yield trailing;
+  }
+}
+async function* readBodyChunks(body, signal) {
+  const asyncIterable = body;
+  if (typeof asyncIterable?.[Symbol.asyncIterator] === "function") {
+    for await (const chunk of asyncIterable) {
+      if (signal?.aborted) {
+        break;
+      }
+      yield chunk;
+    }
+    return;
+  }
+  const stream = body;
+  if (typeof stream.getReader !== "function") {
+    throw new Error("Unsupported hook stream body type");
+  }
+  const reader = stream.getReader();
+  try {
+    while (!signal?.aborted) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+      if (value) {
+        yield value;
+      }
+    }
+  } finally {
+    try {
+      await reader.cancel?.();
+    } catch {
+    }
+    reader.releaseLock?.();
+  }
+}
+function parseSseEvent(rawEvent) {
+  if (!rawEvent) {
+    return null;
+  }
+  let event = "message";
+  let id;
+  const dataLines = [];
+  for (const line of rawEvent.split("\n")) {
+    if (!line || line.startsWith(":")) {
+      continue;
+    }
+    const [field, ...rest] = line.split(":");
+    const value = rest.join(":").replace(/^ /, "");
+    switch (field) {
+      case "event":
+        event = value;
+        break;
+      case "id":
+        id = value;
+        break;
+      case "data":
+        dataLines.push(value);
+        break;
+      default:
+        break;
+    }
+  }
+  if (dataLines.length === 0) {
+    return null;
+  }
+  return {
+    event,
+    id,
+    data: dataLines.join("\n")
+  };
+}
+function parseHookEvent(message) {
+  const parsed = JSON.parse(message.data);
+  return {
+    type: "write",
+    id: parsed.id ?? message.id ?? "",
+    space: parsed.space ?? "",
+    service: parsed.service ?? "",
+    ability: parsed.ability ?? "",
+    path: parsed.path,
+    actor: parsed.actor ?? "",
+    epoch: parsed.epoch ?? "",
+    eventIndex: parsed.eventIndex ?? 0,
+    timestamp: parsed.timestamp ?? ""
+  };
+}
+function normalizeWebhookRecord(data) {
+  if (!data || typeof data !== "object") {
+    return null;
+  }
+  const record = isRecordContainer(data);
+  const candidate = pickWebhookRecord(record) ?? normalizeWebhookRecord(record.webhook) ?? normalizeWebhookRecord(record.hook) ?? normalizeWebhookRecord(record.subscription) ?? normalizeWebhookRecord(record.data);
+  return candidate ?? null;
+}
+function normalizeWebhookRecordList(data) {
+  if (Array.isArray(data)) {
+    const records = data.map((entry) => normalizeWebhookRecord(entry)).filter((entry) => entry !== null);
+    return records;
+  }
+  if (!data || typeof data !== "object") {
+    return null;
+  }
+  const record = isRecordContainer(data);
+  const nested = maybeRecordArray(record.webhooks) ?? maybeRecordArray(record.subscriptions) ?? maybeRecordArray(record.hooks) ?? maybeRecordArray(record.data);
+  if (nested) {
+    return nested;
+  }
+  const single = pickWebhookRecord(record);
+  return single ? [single] : null;
+}
+function maybeRecordArray(value) {
+  if (!Array.isArray(value)) {
+    return null;
+  }
+  const records = value.map((entry) => normalizeWebhookRecord(entry)).filter((entry) => entry !== null);
+  return records;
+}
+function pickWebhookRecord(value) {
+  const id = stringField(value, "id");
+  const space = stringField(value, "space") ?? stringField(value, "spaceId");
+  const service = stringField(value, "service");
+  const callbackUrl = stringField(value, "callbackUrl") ?? stringField(value, "callback_url");
+  if (!id || !space || !service || !callbackUrl) {
+    return null;
+  }
+  return {
+    id,
+    space,
+    service,
+    pathPrefix: optionalStringField(value, "pathPrefix") ?? optionalStringField(value, "path_prefix"),
+    abilities: stringArrayField(value, "abilities") ?? parsedStringArrayField(value, "abilitiesJson") ?? parsedStringArrayField(value, "abilities_json"),
+    callbackUrl,
+    active: booleanField(value, "active") ?? true,
+    createdAt: stringField(value, "createdAt") ?? stringField(value, "created_at") ?? (/* @__PURE__ */ new Date()).toISOString(),
+    subscriberDid: optionalStringField(value, "subscriberDid") ?? optionalStringField(value, "subscriber_did")
+  };
+}
+function isRecordContainer(value) {
+  return value;
+}
+function stringField(value, key) {
+  const field = value[key];
+  return typeof field === "string" ? field : void 0;
+}
+function optionalStringField(value, key) {
+  return stringField(value, key);
+}
+function booleanField(value, key) {
+  const field = value[key];
+  return typeof field === "boolean" ? field : void 0;
+}
+function stringArrayField(value, key) {
+  const field = value[key];
+  if (!Array.isArray(field)) {
+    return void 0;
+  }
+  const strings = field.filter(
+    (item) => typeof item === "string"
+  );
+  return strings.length === field.length ? strings : void 0;
+}
+function parsedStringArrayField(value, key) {
+  const field = value[key];
+  if (typeof field !== "string") {
+    return void 0;
+  }
+  try {
+    const parsed = JSON.parse(field);
+    if (!Array.isArray(parsed)) {
+      return void 0;
+    }
+    const strings = parsed.filter(
+      (item) => typeof item === "string"
+    );
+    return strings.length === parsed.length ? strings : void 0;
+  } catch {
+    return void 0;
+  }
+}
+
 // src/quota/TinyCloudQuota.ts
 var TinyCloudQuota = class {
   constructor(config = {}) {
@@ -3088,6 +3772,7 @@ export {
   ErrorCodes,
   GenericKVResponseSchema,
   GenericResultSchema,
+  HooksService,
   KVAction,
   KVListResponseSchema,
   KVListResultSchema,