@oxyhq/core 20.0.0 → 20.1.0

package/dist/esm/mixins/OxyServices.chains.js

@@ -0,0 +1,70 @@
+/**
+ * Chains — the shared record log every Oxy app reads and writes.
+ *
+ * A person has ONE chain. An app appends its own records to it and projects its
+ * feeds from what it reads back, instead of keeping a private copy of the same
+ * person's activity. This mixin is the client half of `/chains` in oxy-api, and
+ * it exists so that adopting the chain costs an app no HTTP of its own — the
+ * whole point of the shared substrate is that the second app writes less code
+ * than the first, not the same amount in a different file.
+ *
+ * ## Both calls are SERVICE-authenticated
+ *
+ * They go through `makeServiceRequest`, so they only work on a backend that has
+ * called `configureServiceAuth()`. That is not an accident of implementation: an
+ * append writes to someone else's chain and a read spans many subjects, so
+ * neither belongs in a browser holding a user session. A frontend that needs
+ * this asks its own backend.
+ *
+ * The authority is checked server-side and cannot be talked out of from here:
+ * `chains:write` plus the application's own `chainNamespaces` for an append,
+ * `chains:read` plus the public-collection policy for a read. A call that
+ * violates either gets a 403 or an empty page — this client adds no
+ * pre-validation that could drift from the server's answer.
+ */
+export function OxyServicesChainsMixin(Base) {
+    return class extends Base {
+        constructor(...args) {
+            super(...args);
+        }
+        /**
+         * Append a record to `oxyUserId`'s chain under `collection`/`rkey`.
+         *
+         * Oxy issues and signs it; the calling app never holds a chain signing key.
+         * `rkey` is the app's own id for the thing — reusing it later supersedes the
+         * earlier record for that key, which is how an edit works.
+         *
+         * Requires the `chains:write` scope AND `collection` falling under one of
+         * this application's granted `chainNamespaces`. Both are enforced by the
+         * server; a violation throws with a 403.
+         */
+        async appendChainRecord(params) {
+            return this.makeServiceRequest('POST', '/chains/records', params);
+        }
+        /**
+         * Records published by any of `oxyUserIds` under any of `collections`,
+         * oldest first — the read a cross-app feed is projected from.
+         *
+         * Only collections Oxy declares PUBLIC come back, whatever is asked for; a
+         * private one yields nothing rather than an error.
+         *
+         * **Re-poll from slightly BEFORE your last cursor and dedupe by
+         * `recordId`.** The chain's pagination axis is a transaction-start
+         * timestamp, so a record can commit behind a cursor that already passed it.
+         * Re-delivering one costs bytes; skipping one costs a record that never
+         * appears. Projections are expected to be idempotent for exactly this
+         * reason.
+         */
+        async readChainRecords(params) {
+            const query = new URLSearchParams({
+                authors: params.oxyUserIds.join(','),
+                collections: params.collections.join(','),
+            });
+            if (params.since)
+                query.set('since', params.since);
+            if (params.limit !== undefined)
+                query.set('limit', String(params.limit));
+            return this.makeServiceRequest('GET', `/chains/records?${query.toString()}`);
+        }
+    };
+}

package/dist/esm/mixins/OxyServices.store.js

@@ -0,0 +1,263 @@
+import { CACHE_TIMES } from './mixinHelpers.js';
+/** Read one page out of that envelope. */
+function pageOf(res) {
+    return {
+        items: res.data ?? [],
+        total: res.pagination?.total ?? 0,
+        hasMore: res.pagination?.hasMore ?? false,
+    };
+}
+/**
+ * Build a query string from the options that were actually supplied.
+ *
+ * Generic over the options object rather than taking a `Record`: an interface
+ * has no implicit index signature in TypeScript, so `StoreReviewsOptions` would
+ * not be assignable to one and every call site would need a cast.
+ */
+function queryOf(params) {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined)
+            search.set(key, String(value));
+    }
+    const rendered = search.toString();
+    return rendered ? `?${rendered}` : '';
+}
+export function OxyServicesStoreMixin(Base) {
+    return class extends Base {
+        constructor(...args) {
+            super(...args);
+        }
+        // =========================================================================
+        // The storefront — /store. No authentication: everything served is public.
+        // =========================================================================
+        /** The shelves, in the order the store curates them. */
+        async listStoreCategories() {
+            try {
+                const res = await this.makeRequest('GET', '/store/categories', undefined, { cache: true, cacheTTL: CACHE_TIMES.MEDIUM });
+                return res.data ?? [];
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Published listings, newest first, optionally one shelf.
+         *
+         * An unknown category slug is an EMPTY shelf, not every app on the store —
+         * so a typo shows nothing rather than showing everything.
+         *
+         * @param options - `category` is a category slug; `limit` defaults to 24.
+         */
+        async listStoreApps(options = {}) {
+            try {
+                const res = await this.makeRequest('GET', `/store/apps${queryOf(options)}`, undefined, { cache: true, cacheTTL: CACHE_TIMES.SHORT });
+                return pageOf(res);
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * One store page.
+         *
+         * A draft answers 404 exactly as an unknown slug does: whether an
+         * unpublished page exists under a name is not something a visitor learns.
+         *
+         * @param slug - The listing's public slug, not an application id.
+         */
+        async getStoreApp(slug) {
+            try {
+                const res = await this.makeRequest('GET', `/store/apps/${encodeURIComponent(slug)}`, undefined, { cache: true, cacheTTL: CACHE_TIMES.SHORT });
+                return res.data;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /** Visible reviews for a published app, each with the publisher's reply. */
+        async listStoreReviews(slug, options = {}) {
+            try {
+                const res = await this.makeRequest('GET', `/store/apps/${encodeURIComponent(slug)}/reviews${queryOf(options)}`, undefined, { cache: true, cacheTTL: CACHE_TIMES.SHORT });
+                return pageOf(res);
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        // =========================================================================
+        // Reviewing — any signed-in Oxy account
+        // =========================================================================
+        /** The caller's own review of an app, or `null` if they have not written one. */
+        async getMyStoreReview(slug) {
+            try {
+                const res = await this.makeRequest('GET', `/store/apps/${encodeURIComponent(slug)}/review`, undefined, { cache: false });
+                return res.data ?? null;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Write the caller's review, or replace what they said before.
+         *
+         * A person has one review per app, so this sets it rather than adding one.
+         * Rewriting does not clear a moderator's decision: a hidden review stays
+         * hidden when its author edits it.
+         */
+        async writeStoreReview(slug, input) {
+            try {
+                const res = await this.makeRequest('PUT', `/store/apps/${encodeURIComponent(slug)}/review`, input, { cache: false });
+                return res.data;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /** Withdraw the caller's own review. A real delete — the words were theirs. */
+        async deleteMyStoreReview(slug) {
+            try {
+                await this.makeRequest('DELETE', `/store/apps/${encodeURIComponent(slug)}/review`, undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Answer a review on the publisher's behalf.
+         *
+         * Requires `app:update` over the application's owning account — the same
+         * permission that guards every other write to that application. Addressed
+         * by review id because the reply belongs to the review, and a listing can be
+         * renamed or withdrawn out from under it.
+         */
+        async replyToStoreReview(reviewId, body) {
+            try {
+                const res = await this.makeRequest('PUT', `/store/reviews/${encodeURIComponent(reviewId)}/reply`, { body }, { cache: false });
+                return res.data;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /** Withdraw the publisher's answer. Same permission that wrote it. */
+        async deleteStoreReviewReply(reviewId) {
+            try {
+                await this.makeRequest('DELETE', `/store/reviews/${encodeURIComponent(reviewId)}/reply`, undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        // =========================================================================
+        // The publisher's listing — /applications/:appId/listing
+        // =========================================================================
+        /** The application's store page in whatever state, or `null` if it has none. */
+        async getAppListing(applicationId) {
+            try {
+                return await this.makeRequest('GET', `/applications/${encodeURIComponent(applicationId)}/listing`, undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Create the page or replace its content. Never its status.
+         *
+         * Editing does not move a page: correcting a typo on a live listing leaves
+         * it live, and fixing a rejected one does not re-submit it.
+         */
+        async writeAppListing(applicationId, input) {
+            try {
+                return await this.makeRequest('PUT', `/applications/${encodeURIComponent(applicationId)}/listing`, input, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /** Hand the page to the store for review. From a draft, or a rejected page once fixed. */
+        async submitAppListing(applicationId) {
+            try {
+                return await this.makeRequest('POST', `/applications/${encodeURIComponent(applicationId)}/listing/submit`, undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Take the page down, or withdraw it from the queue.
+         *
+         * Back to a draft, never deleted: the slug, the words and the screenshots
+         * are the publisher's work, and the reviews were never the listing's to take
+         * with them.
+         */
+        async unpublishAppListing(applicationId) {
+            try {
+                return await this.makeRequest('POST', `/applications/${encodeURIComponent(applicationId)}/listing/unpublish`, undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        // =========================================================================
+        // Screenshots
+        // =========================================================================
+        /** Every picture on the listing, in the author's order. */
+        async listAppListingScreenshots(applicationId) {
+            try {
+                return await this.makeRequest('GET', `/applications/${encodeURIComponent(applicationId)}/listing/screenshots`, undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Attach an already-uploaded image, appended to the end.
+         *
+         * Upload through the assets surface first; the store keeps a reference
+         * rather than a second copy of the asset pipeline. The file must be live, an
+         * image, and one the caller is entitled to.
+         */
+        async addAppListingScreenshot(applicationId, input) {
+            try {
+                return await this.makeRequest('POST', `/applications/${encodeURIComponent(applicationId)}/listing/screenshots`, input, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /** Edit a picture's caption or the frame it was taken in. Order is {@link reorderAppListingScreenshots}. */
+        async updateAppListingScreenshot(applicationId, screenshotId, input) {
+            try {
+                return await this.makeRequest('PATCH', `/applications/${encodeURIComponent(applicationId)}/listing/screenshots/${encodeURIComponent(screenshotId)}`, input, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /** Remove a picture. The uploaded file stays — it may be in use elsewhere. */
+        async deleteAppListingScreenshot(applicationId, screenshotId) {
+            try {
+                await this.makeRequest('DELETE', `/applications/${encodeURIComponent(applicationId)}/listing/screenshots/${encodeURIComponent(screenshotId)}`, undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Set the order of every picture at once.
+         *
+         * Send EVERY id on the listing, exactly once, in the order they should
+         * appear. A partial list is rejected rather than applied: it would leave the
+         * pictures it omits at their old positions, interleaved with the new ones.
+         */
+        async reorderAppListingScreenshots(applicationId, screenshotIds) {
+            try {
+                return await this.makeRequest('PUT', `/applications/${encodeURIComponent(applicationId)}/listing/screenshots/order`, { screenshotIds }, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+    };
+}