@oxy.so/core 1.0.0

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);
+            }
+        }
+    };
+}

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

@@ -0,0 +1,134 @@
+import { CACHE_TIMES } from './mixinHelpers.js';
+export function OxyServicesTopicsMixin(Base) {
+    return class extends Base {
+        constructor(...args) {
+            super(...args);
+        }
+        /**
+         * Get top-level topic categories
+         * @param locale - Optional locale for translated results
+         * @returns List of category topics
+         */
+        async getTopicCategories(locale) {
+            try {
+                const params = {};
+                if (locale)
+                    params.locale = locale;
+                // `GET /topics/categories` returns `{ categories: TopicData[] }` — the
+                // SDK's `unwrapResponse` only unwraps `{ data }`, so unwrap here.
+                const response = await this.makeRequest('GET', '/topics/categories', params, { cache: true, cacheTTL: CACHE_TIMES.EXTRA_LONG });
+                return response.categories ?? [];
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Search topics by query string
+         * @param query - Search query
+         * @param limit - Optional result limit
+         * @returns Matching topics
+         */
+        async searchTopics(query, limit) {
+            try {
+                const params = { q: query };
+                if (limit)
+                    params.limit = limit;
+                // `GET /topics/search` returns `{ topics: TopicData[] }` — unwrap it.
+                const response = await this.makeRequest('GET', '/topics/search', params, { cache: false });
+                return response.topics ?? [];
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * List topics with optional filters
+         * @param options - Filter and pagination options
+         * @returns Paginated topics envelope (`topics` plus `total`/`limit`/`offset`)
+         */
+        async listTopics(options) {
+            try {
+                const params = {};
+                if (options?.type)
+                    params.type = options.type;
+                if (options?.q)
+                    params.q = options.q;
+                if (options?.limit)
+                    params.limit = options.limit;
+                if (options?.offset)
+                    params.offset = options.offset;
+                if (options?.locale)
+                    params.locale = options.locale;
+                // `GET /topics` returns `{ topics, total, limit, offset }`. The pagination
+                // fields matter to callers, so return the whole envelope (typed) rather
+                // than throwing them away.
+                const response = await this.makeRequest('GET', '/topics', params, { cache: true, cacheTTL: CACHE_TIMES.SHORT });
+                const requestedLimit = typeof params.limit === 'number' ? params.limit : 0;
+                const requestedOffset = typeof params.offset === 'number' ? params.offset : 0;
+                return {
+                    topics: response.topics ?? [],
+                    total: response.total ?? response.topics?.length ?? 0,
+                    limit: response.limit ?? requestedLimit,
+                    offset: response.offset ?? requestedOffset,
+                };
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Get a single topic by slug
+         * @param slug - Topic slug
+         * @returns Topic data
+         */
+        async getTopicBySlug(slug) {
+            try {
+                return await this.makeRequest('GET', `/topics/${slug}`, undefined, {
+                    cache: true,
+                    cacheTTL: CACHE_TIMES.LONG,
+                });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Resolve an array of topic names to existing or newly created topics
+         * @param names - Array of { name, type } objects to resolve
+         * @returns Resolved topic data
+         */
+        async resolveTopicNames(names) {
+            try {
+                // `POST /topics/resolve` returns `{ topics: Record<name, TopicData> }`
+                // (a name-keyed map, not an array). Unwrap and flatten to the resolved
+                // topics; each TopicData carries its own `name` for re-keying.
+                const response = await this.makeRequest('POST', '/topics/resolve', { names }, { cache: false });
+                return Object.values(response.topics ?? {});
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Update metadata for a topic
+         * @param slug - Topic slug
+         * @param data - Metadata fields to update
+         * @returns Updated topic data
+         */
+        async updateTopicMetadata(slug, data) {
+            try {
+                const result = await this.makeRequest('PATCH', `/topics/${slug}`, data, {
+                    cache: false,
+                });
+                // Bust the cached topic detail so `getTopicBySlug(slug)` reflects the
+                // updated metadata immediately (it caches at the LONG TTL).
+                this.clearCacheEntry(`GET:/topics/${slug}`);
+                return result;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+    };
+}