@getopencrawl/sdk 0.0.0-stage → 0.2.1

package/dist/answerView.d.ts

@@ -0,0 +1,40 @@
+import type { AnswerComponent, AnswerContractRun, AnswerContractView, AnswerFactRef } from './answerContract.js';
+export type AnswerAssertion = {
+    text: string;
+    fact_refs: AnswerFactRef[];
+};
+export type AnswerOmissionReason = 'source_scoped_unknown' | 'answer_not_delivered' | 'unassessed' | 'prose_not_supplied' | 'prose_review_failed' | 'fact_binding_failed';
+export type ResearchAnswerView = {
+    version: 1;
+    goal_sha256: string;
+    answer_contract_sha256: string;
+    findings_sha256: string;
+    sections: {
+        component_id: string;
+        assertions: AnswerAssertion[];
+    }[];
+    omitted: {
+        component_id: string;
+        reason: AnswerOmissionReason;
+    }[];
+};
+export type ResearchAnswerSection = {
+    component: AnswerComponent;
+    assertions: AnswerAssertion[];
+    omission_reason: AnswerOmissionReason | null;
+    notice: string | null;
+};
+export type ResearchAnswerViewResult = {
+    state: 'absent' | 'invalid' | 'valid';
+    view: ResearchAnswerView | null;
+    sections: ResearchAnswerSection[];
+};
+/** Python's sorted-key, compact, ensure_ascii=False JSON for bounded public data.
+ * Literal strings are not normalized. Reject lossy JSON values and lone surrogates.
+ */
+export declare function canonicalAnswerJson(value: unknown): string;
+/** The wrappers supply the existing validated contract. Optional failure never
+ * changes a run, its findings/gaps, or the original contract's coverage notices.
+ */
+export declare function readAnswerView(run: AnswerContractRun, contractView: AnswerContractView, hash: (text: string) => string): ResearchAnswerViewResult;
+//# sourceMappingURL=answerView.d.ts.map

package/dist/answerView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"answerView.d.ts","sourceRoot":"","sources":["../src/answerView.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,eAAe,EAAgB,iBAAiB,EAAC,kBAAkB,EAAC,aAAa,EAAC,MAAM,qBAAqB,CAAC;AAE3H,MAAM,MAAM,eAAe,GAAC;IAAC,IAAI,EAAC,MAAM,CAAC;IAAA,SAAS,EAAC,aAAa,EAAE,CAAA;CAAC,CAAC;AACpE,MAAM,MAAM,oBAAoB,GAAC,uBAAuB,GAAC,sBAAsB,GAAC,YAAY,GAAC,oBAAoB,GAAC,qBAAqB,GAAC,qBAAqB,CAAC;AAC9J,MAAM,MAAM,kBAAkB,GAAC;IAAC,OAAO,EAAC,CAAC,CAAC;IAAA,WAAW,EAAC,MAAM,CAAC;IAAA,sBAAsB,EAAC,MAAM,CAAC;IAAA,eAAe,EAAC,MAAM,CAAC;IAAA,QAAQ,EAAC;QAAC,YAAY,EAAC,MAAM,CAAC;QAAA,UAAU,EAAC,eAAe,EAAE,CAAA;KAAC,EAAE,CAAC;IAAA,OAAO,EAAC;QAAC,YAAY,EAAC,MAAM,CAAC;QAAA,MAAM,EAAC,oBAAoB,CAAA;KAAC,EAAE,CAAA;CAAC,CAAC;AAC7O,MAAM,MAAM,qBAAqB,GAAC;IAAC,SAAS,EAAC,eAAe,CAAC;IAAA,UAAU,EAAC,eAAe,EAAE,CAAC;IAAA,eAAe,EAAC,oBAAoB,GAAC,IAAI,CAAC;IAAA,MAAM,EAAC,MAAM,GAAC,IAAI,CAAA;CAAC,CAAC;AACxJ,MAAM,MAAM,wBAAwB,GAAC;IAAC,KAAK,EAAC,QAAQ,GAAC,SAAS,GAAC,OAAO,CAAC;IAAA,IAAI,EAAC,kBAAkB,GAAC,IAAI,CAAC;IAAA,QAAQ,EAAC,qBAAqB,EAAE,CAAA;CAAC,CAAC;AAUtI;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAC,OAAO,GAAE,MAAM,CAexD;AAQD;;GAEG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAC,iBAAiB,EAAC,YAAY,EAAC,kBAAkB,EAAC,IAAI,EAAC,CAAC,IAAI,EAAC,MAAM,KAAG,MAAM,GAAE,wBAAwB,CAmDxI"}

package/dist/answerView.js

@@ -0,0 +1,118 @@
+const obj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const keys = (v, names) => Object.keys(v).length === names.length && names.every(k => Object.hasOwn(v, k));
+const need = (ok) => { if (!ok)
+    throw new Error('Invalid optional concise answer'); };
+const digest = (v) => typeof v === 'string' && /^[a-f0-9]{64}$/.test(v);
+const refKey = (r) => JSON.stringify([r.finding_id, r.field, r.qualifier_ordinal, r.literal_text_sha256]);
+const empty = (state) => ({ state, view: null, sections: [] });
+const byteLength = (text) => new TextEncoder().encode(text).length;
+/** Python's sorted-key, compact, ensure_ascii=False JSON for bounded public data.
+ * Literal strings are not normalized. Reject lossy JSON values and lone surrogates.
+ */
+export function canonicalAnswerJson(value) {
+    let nodes = 0;
+    const scalar = (text) => { need(!/[\uD800-\uDFFF]/u.test(text)); return JSON.stringify(text); };
+    const compare = (a, b) => { const x = Array.from(a), y = Array.from(b); for (let i = 0; i < Math.min(x.length, y.length); i++) {
+        const d = x[i].codePointAt(0) - y[i].codePointAt(0);
+        if (d)
+            return d;
+    } return x.length - y.length; };
+    const encode = (v, depth) => {
+        need(++nodes <= 8192 && depth <= 24);
+        if (v === null)
+            return 'null';
+        if (typeof v === 'string')
+            return scalar(v);
+        if (typeof v === 'boolean')
+            return v ? 'true' : 'false';
+        if (typeof v === 'number') {
+            need(Number.isSafeInteger(v) && !Object.is(v, -0));
+            return String(v);
+        }
+        if (Array.isArray(v))
+            return '[' + Array.from(v, item => encode(item, depth + 1)).join(',') + ']';
+        need(obj(v) && (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null));
+        return '{' + Object.keys(v).sort(compare).map(k => scalar(k) + ':' + encode(v[k], depth + 1)).join(',') + '}';
+    };
+    const result = encode(value, 0);
+    need(byteLength(result) <= 65536);
+    return result;
+}
+function omission(c, reason) {
+    if (reason === 'source_scoped_unknown')
+        return 'Not established in the saved sources for this part.';
+    if (reason === 'answer_not_delivered')
+        return 'Answer material was found in the saved source text, but a complete answer was not retained in this result.';
+    return c.status === 'unassessed' ? 'Review the exact evidence for this part. Requested-answer coverage was not assessed.' : 'Review the exact evidence for this part. Concise prose was not retained.';
+}
+/** The wrappers supply the existing validated contract. Optional failure never
+ * changes a run, its findings/gaps, or the original contract's coverage notices.
+ */
+export function readAnswerView(run, contractView, hash) {
+    if (!Object.hasOwn(run.usage, 'answer_view'))
+        return empty('absent');
+    try {
+        need(contractView.state === 'assessed_nonexhaustive' && contractView.contract !== null);
+        const contract = contractView.contract, value = run.usage.answer_view;
+        need(obj(value));
+        const v = value;
+        need(keys(v, ['version', 'goal_sha256', 'answer_contract_sha256', 'findings_sha256', 'sections', 'omitted']) && v.version === 1);
+        need(byteLength(canonicalAnswerJson(v)) <= 8192 && byteLength(canonicalAnswerJson(run.usage)) <= 16384);
+        need(run.findings.length <= 5 && run.findings.every(f => f.qualifiers.length <= 5 && [f.claim, ...f.qualifiers].every(t => typeof t === 'string' && Array.from(t).length <= 1500)));
+        need(digest(v.goal_sha256) && v.goal_sha256 === contract.goal_sha256 && digest(v.answer_contract_sha256) && digest(v.findings_sha256));
+        need(hash(canonicalAnswerJson(run.usage.answer_contract)) === v.answer_contract_sha256 && hash(canonicalAnswerJson(run.findings)) === v.findings_sha256);
+        need(Array.isArray(v.sections) && v.sections.length <= 8 && Array.isArray(v.omitted) && v.omitted.length <= 8);
+        const ordered = [...contract.components].sort((a, b) => a.start - b.start || a.end - b.end), byId = new Map(ordered.map(c => [c.component_id, c]));
+        const sections = new Map(), omitted = new Map();
+        let total = 0;
+        for (const s of v.sections) {
+            need(obj(s) && keys(s, ['component_id', 'assertions']) && !sections.has(s.component_id));
+            const c = byId.get(s.component_id);
+            need(c && ['literal_answer', 'literal_negative_answer'].includes(c.status));
+            need(Array.isArray(s.assertions) && s.assertions.length >= 1 && s.assertions.length <= 2);
+            const expected = new Set(c.fact_refs.map(refKey)), actual = new Set();
+            for (const a of s.assertions) {
+                need(obj(a) && keys(a, ['text', 'fact_refs']) && typeof a.text === 'string' && a.text === a.text.trim() && a.text.length > 0 && !/\p{C}/u.test(a.text));
+                total += Array.from(a.text).length;
+                need(total <= 1800);
+                need(Array.isArray(a.fact_refs) && a.fact_refs.length >= 1 && a.fact_refs.length <= 10);
+                const own = new Set();
+                for (const r of a.fact_refs) {
+                    need(obj(r) && keys(r, ['finding_id', 'field', 'qualifier_ordinal', 'literal_text_sha256']));
+                    const finding = run.findings.find(f => f.id === r.finding_id);
+                    need(finding && ['claim', 'qualifier'].includes(r.field) && Number.isSafeInteger(r.qualifier_ordinal) && digest(r.literal_text_sha256));
+                    need(r.field === 'claim' ? r.qualifier_ordinal === 0 : r.qualifier_ordinal >= 1 && r.qualifier_ordinal <= finding.qualifiers.length);
+                    const literal = r.field === 'claim' ? finding.claim : finding.qualifiers[r.qualifier_ordinal - 1];
+                    need(typeof literal === 'string' && hash(literal) === r.literal_text_sha256);
+                    const key = refKey(r);
+                    need(!own.has(key));
+                    own.add(key);
+                    actual.add(key);
+                }
+            }
+            // Extra reviewed, retained fields may carry necessary context. They never
+            // substitute for a required component field or a missing qualification.
+            need([...expected].every(key => actual.has(key)));
+            sections.set(s.component_id, s.assertions);
+        }
+        for (const o of v.omitted) {
+            need(obj(o) && keys(o, ['component_id', 'reason']) && !sections.has(o.component_id) && !omitted.has(o.component_id));
+            const c = byId.get(o.component_id);
+            need(c);
+            const allowed = c.status === 'source_scoped_unknown_assessment' ? ['source_scoped_unknown'] : c.status === 'available_but_not_delivered' ? ['answer_not_delivered'] : c.status === 'unassessed' ? ['unassessed'] : ['prose_not_supplied', 'prose_review_failed', 'fact_binding_failed'];
+            need(allowed.includes(o.reason));
+            omitted.set(o.component_id, o.reason);
+        }
+        need(sections.size + omitted.size === ordered.length);
+        need(JSON.stringify([...sections.keys()]) === JSON.stringify(ordered.filter(c => sections.has(c.component_id)).map(c => c.component_id)));
+        need(JSON.stringify([...omitted.keys()]) === JSON.stringify(ordered.filter(c => omitted.has(c.component_id)).map(c => c.component_id)));
+        return { state: 'valid', view: structuredClone(v), sections: structuredClone(ordered.map(component => {
+                const reason = omitted.get(component.component_id) ?? null;
+                return { component, assertions: sections.get(component.component_id) ?? [], omission_reason: reason, notice: reason === null ? null : omission(component, reason) };
+            })) };
+    }
+    catch {
+        return empty('invalid');
+    }
+}
+//# sourceMappingURL=answerView.js.map

package/dist/answerView.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"answerView.js","sourceRoot":"","sources":["../src/answerView.ts"],"names":[],"mappings":"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"}

package/dist/configuration.d.ts

@@ -0,0 +1,5 @@
+import { Transport, type MutationOptions } from './transport.js';
+import type { CollectionSettings, CollectionSettingsReceipt } from './types.js';
+/** Saves reviewed operating limits once. Source scope/history are unchanged. */
+export declare function configureCollection(transport: Transport, id: string, input: CollectionSettings, options: MutationOptions): Promise<CollectionSettingsReceipt>;
+//# sourceMappingURL=configuration.d.ts.map

package/dist/configuration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"configuration.d.ts","sourceRoot":"","sources":["../src/configuration.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,SAAS,EAAsC,KAAK,eAAe,EAAC,MAAM,gBAAgB,CAAC;AACnG,OAAO,KAAK,EAAC,kBAAkB,EAAC,yBAAyB,EAAC,MAAM,YAAY,CAAC;AAE7E,gFAAgF;AAChF,wBAAsB,mBAAmB,CAAC,SAAS,EAAC,SAAS,EAAC,EAAE,EAAC,MAAM,EAAC,KAAK,EAAC,kBAAkB,EAAC,OAAO,EAAC,eAAe,GAAE,OAAO,CAAC,yBAAyB,CAAC,CAe3J"}

package/dist/configuration.js

@@ -0,0 +1,29 @@
+import { OpenCrawlProtocolError, OpenCrawlValidationError } from './errors.js';
+import { boundedInteger, idPath, idempotencyKey } from './transport.js';
+/** Saves reviewed operating limits once. Source scope/history are unchanged. */
+export async function configureCollection(transport, id, input, options) {
+    const path = idPath(id);
+    idempotencyKey(options?.idempotencyKey);
+    const fields = ['expected_revision', 'page_limit', 'schedule_minutes', 'include_media'];
+    if (!input || typeof input !== 'object' || Array.isArray(input) || Object.keys(input).some(key => !fields.includes(key)))
+        throw new OpenCrawlValidationError('Use only the reviewed revision, page limit, refresh interval and media choice.');
+    const body = { expected_revision: input.expected_revision, page_limit: input.page_limit, schedule_minutes: input.schedule_minutes, include_media: input.include_media };
+    boundedInteger(body.expected_revision, 'expected_revision', 1, Number.MAX_SAFE_INTEGER);
+    boundedInteger(body.page_limit, 'page_limit', 1, 5000);
+    boundedInteger(body.schedule_minutes, 'schedule_minutes', 0, 10080);
+    if (body.schedule_minutes > 0 && body.schedule_minutes < 5 || typeof body.include_media !== 'boolean')
+        throw new OpenCrawlValidationError('Choose manual or at least five minutes, and an explicit boolean media choice.');
+    const value = await transport.request(`/api/research/collections/${path}/configure`, { ...options, method: 'POST', body, automaticRetry: false });
+    const collection = value?.collection;
+    const invalid = () => new OpenCrawlProtocolError('The settings receipt could not be confirmed. Recover with the original idempotency key and exact descriptor; do not assume the settings were saved.');
+    if (!collection || collection.id !== id || !['active', 'paused'].includes(collection.status) || typeof value.replayed !== 'boolean' || 'job' in value || !Number.isSafeInteger(collection.revision) || ![body.expected_revision, body.expected_revision + 1].includes(collection.revision) || collection.page_limit !== body.page_limit || collection.schedule_minutes !== body.schedule_minutes || collection.include_media !== body.include_media)
+        throw invalid();
+    if (collection.status === 'paused' || body.schedule_minutes === 0) {
+        if (value.next_scheduled_at !== null)
+            throw invalid();
+    }
+    else if (!(collection.revision === body.expected_revision && value.next_scheduled_at === null) && (typeof value.next_scheduled_at !== 'string' || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,6})?Z$/.test(value.next_scheduled_at) || !Number.isFinite(Date.parse(value.next_scheduled_at)) || new Date(value.next_scheduled_at).toISOString().slice(0, 19) !== value.next_scheduled_at.slice(0, 19)))
+        throw invalid();
+    return value;
+}
+//# sourceMappingURL=configuration.js.map

package/dist/configuration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"configuration.js","sourceRoot":"","sources":["../src/configuration.ts"],"names":[],"mappings":"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"}

package/dist/customers.d.ts

@@ -0,0 +1,176 @@
+import type { RequestOptions } from './transport.js';
+import type { Collection, ResearchEvent, ServiceTenantReceipt, ServiceTenantInput, ServiceTenantRevision, ServiceTenantPage, ServiceTenantListOptions, CursorPage, CollectionInput, CollectionReceipt } from './types.js';
+import type { ResearchAgent, ResearchAgentReceipt, ResearchAgentRun, ResearchAgentInput, ResearchAgentRunInput, ResearchAgentPage, AgentWaitOptions } from './agents.js';
+import type { MutationOptions } from './transport.js';
+/** Where each customer's OpenCrawl key lives. Use shared storage (database, Redis,
+ * secrets manager) when more than one process serves customers. */
+export type KeyStore = {
+    get(customerId: string): Promise<string | null | undefined> | string | null | undefined;
+    set(customerId: string, key: string): Promise<void> | void;
+};
+export type CustomerProfile = {
+    id: string;
+    name: string;
+    website: string;
+    context?: string;
+};
+export type Cadence = 'hour' | 'day' | 'week';
+export type WatchInput = {
+    name: string;
+    urls: string[];
+    every?: Cadence;
+    brief?: string;
+};
+export type Watch = {
+    id: string;
+    name: string;
+    urls: string[];
+    every: Cadence | number;
+    status: 'active' | 'paused';
+    lastCheckedAt: string | null;
+    createdAt: string;
+};
+export type Signal = {
+    id: string;
+    watchId: string;
+    watchName: string;
+    url: string;
+    kind: 'changed' | 'unavailable' | 'recovered';
+    observedAt: string;
+    previousObservedAt: string | null;
+    headline: string;
+    relevance: 'high' | 'medium' | 'low' | null;
+    relevanceReason: string | null;
+    changes: {
+        removed: string[];
+        added: string[];
+    }[];
+    truncated: boolean;
+    gap: boolean;
+};
+export type SignalsOptions = RequestOptions & {
+    since?: string | null;
+    watchId?: string;
+    limit?: number;
+};
+export type SignalsResult = {
+    signals: Signal[];
+    cursor: string | null;
+    more: boolean;
+};
+export type AnswerSource = {
+    url: string;
+    title: string;
+    quote: string;
+    publishedAt: string | null;
+};
+export type AnswerFinding = {
+    claim: string;
+    qualifiers: string[];
+    sources: AnswerSource[];
+};
+export type Answer = {
+    answerId: string;
+    question: string;
+    status: ResearchAgentRun['status'];
+    done: boolean;
+    findings: AnswerFinding[];
+    gaps: string[];
+    startedAt: string;
+    finishedAt: string | null;
+};
+export type AskOptions = RequestOptions & {
+    urls?: string[];
+    waitMs?: number;
+    reuseWithinMs?: number;
+};
+export type McpConnection = {
+    url: string;
+    headers: {
+        Authorization: string;
+    };
+};
+type ChildClient = {
+    collections: {
+        create(input: CollectionInput, options: MutationOptions): Promise<CollectionReceipt>;
+        list(options?: RequestOptions & {
+            limit?: number;
+            cursor?: string;
+        }): Promise<CursorPage<Collection>>;
+        get(id: string, options?: RequestOptions): Promise<Collection>;
+        update(id: string, input: {
+            expected_revision: number;
+            status: 'active' | 'paused';
+        }, options?: RequestOptions): Promise<Collection>;
+        events(id: string, options?: RequestOptions & {
+            limit?: number;
+            cursor?: string;
+            includeVolatile?: boolean;
+        }): Promise<CursorPage<ResearchEvent>>;
+    };
+    agents: {
+        create(input: ResearchAgentInput, options: MutationOptions): Promise<ResearchAgentReceipt>;
+        get(id: string, options?: RequestOptions): Promise<ResearchAgent>;
+        list(options?: RequestOptions & {
+            limit?: number;
+            cursor?: string;
+        }): Promise<ResearchAgentPage>;
+        runs: {
+            create(agentId: string, input: ResearchAgentRunInput, options: MutationOptions): Promise<ResearchAgentReceipt>;
+            get(agentId: string, runId: string, options?: RequestOptions): Promise<ResearchAgentRun>;
+            wait(agentId: string, runId: string, options?: AgentWaitOptions): Promise<ResearchAgentRun>;
+        };
+    };
+    readonly baseUrl: string;
+};
+type ParentClient = {
+    createServiceTenant(input: ServiceTenantInput, options: MutationOptions): Promise<ServiceTenantReceipt>;
+    listServiceTenants(options?: ServiceTenantListOptions & RequestOptions): Promise<ServiceTenantPage>;
+    rotateServiceTenantKey(id: string, input: ServiceTenantRevision, options: MutationOptions): Promise<ServiceTenantReceipt>;
+};
+/** Process-local key cache. Lost keys are recovered by rotation, so this is safe for
+ * a single process; with several processes use a shared KeyStore. */
+export declare function memoryKeyStore(): KeyStore;
+/** Deterministic description of one change for a feed or an agent. Prefers a
+ * server-generated headline when the observation carries one. */
+export declare function signalHeadline(event: Pick<ResearchEvent, 'kind' | 'url'> & {
+    change_summary: ResearchEvent['change_summary'] & {
+        headline?: string | null;
+    };
+}): string;
+/** One Letter customer, isolated in its own OpenCrawl workspace. */
+export declare class Customer {
+    #private;
+    readonly id: string;
+    readonly profile: Readonly<CustomerProfile>;
+    constructor(profile: CustomerProfile, client: ChildClient, key: () => string, refresh: () => Promise<ChildClient>);
+    /** The underlying customer-scoped client, for anything not covered here. */
+    get client(): ChildClient;
+    /** Watch public pages for changes. Calling again with the same name, pages and
+    * cadence returns the same watch (resuming it if it was stopped). */
+    watch(input: WatchInput, options?: RequestOptions): Promise<Watch>;
+    watches(options?: RequestOptions): Promise<Watch[]>;
+    /** Stop checking a watch. History and earlier signals are kept. */
+    unwatch(watchId: string, options?: RequestOptions): Promise<Watch>;
+    /** Content changes, unavailable pages and recoveries after `since` (the cursor from the
+    * previous call), oldest first. Date-, clock- and age-only edits are left out. */
+    signals(options?: SignalsOptions): Promise<SignalsResult>;
+    /** Research a question on the public web (or on up to three named pages) and wait up
+    * to `waitMs` for cited findings. Asking the same question again reuses a recent answer. */
+    ask(question: string, options?: AskOptions): Promise<Answer>;
+    /** Read an answer started earlier, optionally waiting for it to finish. */
+    answer(answerId: string, options?: RequestOptions & {
+        waitMs?: number;
+    }): Promise<Answer>;
+    /** Connection details for OpenCrawl's hosted MCP server, scoped to this customer. */
+    mcp(): McpConnection;
+}
+/** Customer isolation for a platform serving many end customers with one admin key. */
+export declare class Customers {
+    #private;
+    constructor(parent: ParentClient, keys: KeyStore, make: (key: string) => ChildClient);
+    /** Load a customer, provisioning its isolated workspace on first use. */
+    get(profile: CustomerProfile, options?: RequestOptions): Promise<Customer>;
+}
+export {};
+//# sourceMappingURL=customers.d.ts.map

package/dist/customers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"customers.d.ts","sourceRoot":"","sources":["../src/customers.ts"],"names":[],"mappings":"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"}