@geoprotocol/geo-sdk 0.18.3 → 0.19.0

package/dist/src/client/images-storage.test.js

@@ -0,0 +1,52 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createGeoClient } from '../client.js';
+import { IMAGE_URL_PROPERTY } from '../core/ids/system.js';
+import { toGrcId } from '../id-utils.js';
+import { defineGeoNetworkConfig } from '../networks.js';
+const CID = 'ipfs://bafkreigwfjixq5cm3s4youhshorkpqh3ykpviyv76c2ei6gaalujtlqz5i';
+const IMAGE_ID = '3af3e22d21694a078681516710b7ecf1';
+function customNetwork() {
+    return defineGeoNetworkConfig({
+        id: 'LOCAL',
+        name: 'Local Geo',
+        apiOrigin: 'http://localhost:3000',
+    });
+}
+function mockUploadFetch() {
+    return vi.fn().mockImplementation(async () => new Response(JSON.stringify({ cid: CID })));
+}
+function imageUrlValue(entityOp) {
+    return entityOp.values.find(value => value.property.every((byte, index) => byte === toGrcId(IMAGE_URL_PROPERTY)[index]));
+}
+describe('geo image and storage clients', () => {
+    it('uploads an image through the configured API origin before creating image ops', async () => {
+        const fetch = mockUploadFetch();
+        const geo = createGeoClient({ network: customNetwork(), fetch });
+        const result = await geo.images.create({
+            id: IMAGE_ID,
+            name: 'Test image',
+            blob: new Blob([new Uint8Array([0, 0, 0, 0])], { type: 'image/png' }),
+        });
+        const entityOp = result.ops[0];
+        const urlValue = imageUrlValue(entityOp);
+        expect(result.id).toBe(IMAGE_ID);
+        expect(result.cid).toBe(CID);
+        expect(urlValue?.value.type).toBe('text');
+        if (urlValue?.value.type === 'text') {
+            expect(urlValue.value.value).toBe(CID);
+        }
+        expect(fetch).toHaveBeenCalledWith('http://localhost:3000/ipfs/upload-file', expect.objectContaining({ method: 'POST' }));
+    });
+    it('uses configured upload routes for storage helpers', async () => {
+        const fetch = mockUploadFetch();
+        const geo = createGeoClient({ network: customNetwork(), fetch });
+        await expect(geo.storage.uploadImage({
+            blob: new Blob([new Uint8Array([0, 0, 0, 0])], { type: 'image/png' }),
+            alternativeGateway: true,
+        })).resolves.toEqual({ cid: CID });
+        await expect(geo.storage.uploadCSV('a,b\n1,2')).resolves.toBe(CID);
+        expect(fetch).toHaveBeenNthCalledWith(1, 'http://localhost:3000/ipfs/upload-file-alternative-gateway', expect.objectContaining({ method: 'POST' }));
+        expect(fetch).toHaveBeenNthCalledWith(2, 'http://localhost:3000/ipfs/upload-edit', expect.objectContaining({ method: 'POST' }));
+    });
+});
+//# sourceMappingURL=images-storage.test.js.map

package/dist/src/client/images-storage.test.js.map

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

package/dist/src/client/images.d.ts

@@ -0,0 +1,35 @@
+import { Id } from '../id.js';
+import { type PublishImageParams } from '../ipfs-core.js';
+import type { CreateImageResult } from '../types.js';
+import type { GeoClientContext } from './context.js';
+export type CreateImageParams = PublishImageParams & {
+    name?: string;
+    description?: string;
+    id?: Id | string;
+    alternativeGateway?: boolean;
+};
+/**
+ * Uploads an image and builds the corresponding image entity ops.
+ *
+ * This is the context-aware image workflow used by `geo.images.create(...)`.
+ * It uploads the image through the configured API origin, attempts to read
+ * image dimensions, then creates image entity ops.
+ *
+ * @example
+ * ```ts
+ * const { id, cid, dimensions, ops } = await geo.images.create({
+ *   url: 'https://example.com/cover.png',
+ *   name: 'Cover image',
+ *   description: 'Image used as the space cover.',
+ * });
+ *
+ * console.log(id, cid, dimensions);
+ * ```
+ *
+ * @param context Client context containing network and fetch configuration.
+ * @param params Image source plus optional entity metadata.
+ * @returns Created image entity ID, uploaded CID, dimensions when detected, and ops.
+ * @throws When the optional ID is invalid, fetch is unavailable, upload fails, or the CID response is invalid.
+ */
+export declare function create(context: GeoClientContext, params: CreateImageParams): Promise<CreateImageResult>;
+//# sourceMappingURL=images.d.ts.map

package/dist/src/client/images.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"images.d.ts","sourceRoot":"","sources":["../../../src/client/images.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAE9B,OAAO,EAAE,KAAK,kBAAkB,EAAmB,MAAM,iBAAiB,CAAC;AAE3E,OAAO,KAAK,EAAE,iBAAiB,EAAmB,MAAM,aAAa,CAAC;AACtE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGrD,MAAM,MAAM,iBAAiB,GAAG,kBAAkB,GAAG;IACnD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,EAAE,CAAC,EAAE,EAAE,GAAG,MAAM,CAAC;IACjB,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,MAAM,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,iBAAiB,8BAgBhF"}

package/dist/src/client/images.js

@@ -0,0 +1,90 @@
+import { createRelation as grcCreateRelation } from '@geoprotocol/grc-20';
+import { IMAGE_HEIGHT_PROPERTY, IMAGE_TYPE, IMAGE_URL_PROPERTY, IMAGE_WIDTH_PROPERTY, TYPES_PROPERTY, } from '../core/ids/system.js';
+import { Id } from '../id.js';
+import { assertValid, generate, toGrcId } from '../id-utils.js';
+import { uploadImageCore } from '../ipfs-core.js';
+import { create as createEntity } from '../ops/entities.js';
+import { requireFetch } from './context.js';
+/**
+ * Uploads an image and builds the corresponding image entity ops.
+ *
+ * This is the context-aware image workflow used by `geo.images.create(...)`.
+ * It uploads the image through the configured API origin, attempts to read
+ * image dimensions, then creates image entity ops.
+ *
+ * @example
+ * ```ts
+ * const { id, cid, dimensions, ops } = await geo.images.create({
+ *   url: 'https://example.com/cover.png',
+ *   name: 'Cover image',
+ *   description: 'Image used as the space cover.',
+ * });
+ *
+ * console.log(id, cid, dimensions);
+ * ```
+ *
+ * @param context Client context containing network and fetch configuration.
+ * @param params Image source plus optional entity metadata.
+ * @returns Created image entity ID, uploaded CID, dimensions when detected, and ops.
+ * @throws When the optional ID is invalid, fetch is unavailable, upload fails, or the CID response is invalid.
+ */
+export async function create(context, params) {
+    if (params.id)
+        assertValid(params.id, '`id` in `createImage`');
+    const { cid, dimensions } = await uploadImageCore({
+        ...params,
+        apiOrigin: context.network.apiOrigin,
+        fetch: requireFetch(context, 'Image creation'),
+    });
+    return createImageOps({
+        id: params.id,
+        name: params.name,
+        description: params.description,
+        cid,
+        dimensions,
+    });
+}
+function createImageOps({ cid, dimensions, name, description, id: providedId, }) {
+    const id = providedId ?? generate();
+    const values = [
+        {
+            property: IMAGE_URL_PROPERTY,
+            type: 'text',
+            value: cid,
+        },
+    ];
+    if (dimensions?.height) {
+        values.push({
+            property: IMAGE_HEIGHT_PROPERTY,
+            type: 'float',
+            value: dimensions.height,
+        });
+    }
+    if (dimensions?.width) {
+        values.push({
+            property: IMAGE_WIDTH_PROPERTY,
+            type: 'float',
+            value: dimensions.width,
+        });
+    }
+    const result = createEntity({
+        id,
+        name,
+        description,
+        values,
+    });
+    result.ops.push(grcCreateRelation({
+        id: toGrcId(generate()),
+        entity: toGrcId(generate()),
+        from: toGrcId(id),
+        to: toGrcId(IMAGE_TYPE),
+        relationType: toGrcId(TYPES_PROPERTY),
+    }));
+    return {
+        id: Id(id),
+        cid,
+        dimensions,
+        ops: result.ops,
+    };
+}
+//# sourceMappingURL=images.js.map

package/dist/src/client/images.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"images.js","sourceRoot":"","sources":["../../../src/client/images.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,IAAI,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC1E,OAAO,EACL,qBAAqB,EACrB,UAAU,EACV,kBAAkB,EAClB,oBAAoB,EACpB,cAAc,GACf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAC9B,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,EAA2B,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAC3E,OAAO,EAAE,MAAM,IAAI,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAG5D,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAS5C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,OAAyB,EAAE,MAAyB;IAC/E,IAAI,MAAM,CAAC,EAAE;QAAE,WAAW,CAAC,MAAM,CAAC,EAAE,EAAE,uBAAuB,CAAC,CAAC;IAE/D,MAAM,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,MAAM,eAAe,CAAC;QAChD,GAAG,MAAM;QACT,SAAS,EAAE,OAAO,CAAC,OAAO,CAAC,SAAS;QACpC,KAAK,EAAE,YAAY,CAAC,OAAO,EAAE,gBAAgB,CAAC;KAC/C,CAAC,CAAC;IAEH,OAAO,cAAc,CAAC;QACpB,EAAE,EAAE,MAAM,CAAC,EAAE;QACb,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,GAAG;QACH,UAAU;KACX,CAAC,CAAC;AACL,CAAC;AAUD,SAAS,cAAc,CAAC,EACtB,GAAG,EACH,UAAU,EACV,IAAI,EACJ,WAAW,EACX,EAAE,EAAE,UAAU,GACO;IACrB,MAAM,EAAE,GAAG,UAAU,IAAI,QAAQ,EAAE,CAAC;IACpC,MAAM,MAAM,GAAoB;QAC9B;YACE,QAAQ,EAAE,kBAAkB;YAC5B,IAAI,EAAE,MAAM;YACZ,KAAK,EAAE,GAAG;SACX;KACF,CAAC;IAEF,IAAI,UAAU,EAAE,MAAM,EAAE,CAAC;QACvB,MAAM,CAAC,IAAI,CAAC;YACV,QAAQ,EAAE,qBAAqB;YAC/B,IAAI,EAAE,OAAO;YACb,KAAK,EAAE,UAAU,CAAC,MAAM;SACzB,CAAC,CAAC;IACL,CAAC;IACD,IAAI,UAAU,EAAE,KAAK,EAAE,CAAC;QACtB,MAAM,CAAC,IAAI,CAAC;YACV,QAAQ,EAAE,oBAAoB;YAC9B,IAAI,EAAE,OAAO;YACb,KAAK,EAAE,UAAU,CAAC,KAAK;SACxB,CAAC,CAAC;IACL,CAAC;IAED,MAAM,MAAM,GAAG,YAAY,CAAC;QAC1B,EAAE;QACF,IAAI;QACJ,WAAW;QACX,MAAM;KACP,CAAC,CAAC;IAEH,MAAM,CAAC,GAAG,CAAC,IAAI,CACb,iBAAiB,CAAC;QAChB,EAAE,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC;QACvB,MAAM,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC;QAC3B,IAAI,EAAE,OAAO,CAAC,EAAE,CAAC;QACjB,EAAE,EAAE,OAAO,CAAC,UAAU,CAAC;QACvB,YAAY,EAAE,OAAO,CAAC,cAAc,CAAC;KACtC,CAAC,CACH,CAAC;IAEF,OAAO;QACL,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC;QACV,GAAG;QACH,UAAU;QACV,GAAG,EAAE,MAAM,CAAC,GAAG;KAChB,CAAC;AACJ,CAAC"}

package/dist/src/client/personal-spaces.d.ts

@@ -0,0 +1,155 @@
+import type { Op } from '@geoprotocol/grc-20';
+import { type Address, type Hex } from 'viem';
+import type { Id } from '../id.js';
+import type { PublishEditParams } from '../ipfs-core.js';
+import type { GeoClientContext } from './context.js';
+export type CreatePersonalSpaceParams = {
+    name: string;
+    accountAddress: Address;
+};
+export type CreatePersonalSpaceResult = {
+    to: `0x${string}`;
+    calldata: `0x${string}`;
+    spaceEntityId: Id;
+    accountId: string;
+    ops: Op[];
+};
+export type SetPersonalSpaceTopicParams = {
+    spaceId: Id | string;
+    topicId: Id | string;
+    authorSpaceId?: Id | string;
+};
+export type HasSpaceParams = {
+    address: Hex;
+    rpcUrl?: string;
+};
+export type PublishPersonalSpaceEditParams = PublishEditParams & {
+    spaceId: Id | string;
+};
+/**
+ * Builds the personal-space creation transaction and initial space content ops.
+ *
+ * The returned calldata registers the caller's address as a personal space.
+ * The returned ops create the space entity, the account entity, and the
+ * personal-space type relations that should be published after the space ID is
+ * available onchain.
+ *
+ * @example
+ * ```ts
+ * const tx = geo.personalSpaces.create({
+ *   name: 'Alice',
+ *   accountAddress: account.address,
+ * });
+ *
+ * await walletClient.sendTransaction({
+ *   to: tx.to,
+ *   data: tx.calldata,
+ * });
+ *
+ * // Once the transaction is mined and the space ID is known:
+ * await geo.personalSpaces.publishEdit({
+ *   name: 'Create personal space profile',
+ *   spaceId,
+ *   author: spaceId,
+ *   ops: tx.ops,
+ * });
+ * ```
+ *
+ * @param context Client context containing the target network configuration.
+ * @param params Space display name and account address to describe in initial ops.
+ * @returns Target registry address, calldata, generated entity IDs, and initial content ops.
+ * @throws When the configured network is missing `SPACE_REGISTRY_ADDRESS`.
+ */
+export declare function create(context: GeoClientContext, { name, accountAddress }: CreatePersonalSpaceParams): CreatePersonalSpaceResult;
+/**
+ * Builds calldata for setting a personal space topic.
+ *
+ * Call this right after creating the personal space and publishing its initial
+ * profile ops. For personal spaces, `authorSpaceId` defaults to `spaceId`.
+ *
+ * @example
+ * ```ts
+ * const topicTx = geo.personalSpaces.setTopic({
+ *   spaceId,
+ *   topicId: createSpace.spaceEntityId,
+ * });
+ *
+ * await walletClient.sendTransaction({
+ *   to: topicTx.to,
+ *   data: topicTx.calldata,
+ * });
+ * ```
+ *
+ * @param context Client context containing the target network configuration.
+ * @param params Space ID, topic entity ID, and optional author space ID.
+ * @returns Target registry address and calldata.
+ * @throws When an ID is invalid or the configured network is missing `SPACE_REGISTRY_ADDRESS`.
+ */
+export declare function setTopic(context: GeoClientContext, { spaceId, topicId, authorSpaceId }: SetPersonalSpaceTopicParams): {
+    to: `0x${string}`;
+    calldata: `0x${string}`;
+};
+/**
+ * Checks whether an address already has a personal space on the configured network.
+ *
+ * The helper reads `addressToSpaceId(address)` from the configured
+ * `SPACE_REGISTRY_ADDRESS`. Pass `rpcUrl` to override the network's configured
+ * RPC URL for this lookup.
+ *
+ * @example
+ * ```ts
+ * const hasExistingSpace = await geo.personalSpaces.hasSpace({
+ *   address: account.address,
+ * });
+ *
+ * if (!hasExistingSpace) {
+ *   const tx = geo.personalSpaces.create({
+ *     name: 'Alice',
+ *     accountAddress: account.address,
+ *   });
+ *   await walletClient.sendTransaction({ to: tx.to, data: tx.calldata });
+ * }
+ * ```
+ *
+ * @param context Client context containing network and contract configuration.
+ * @param params Wallet or smart-account address plus optional RPC URL override.
+ * @returns `true` when the registry maps the address to a non-empty space ID.
+ * @throws When the configured network is missing `SPACE_REGISTRY_ADDRESS` or no RPC URL is available.
+ */
+export declare function hasSpace(context: GeoClientContext, { address, rpcUrl }: HasSpaceParams): Promise<boolean>;
+/**
+ * Publishes an edit and returns calldata for submitting it to a personal space.
+ *
+ * This is the context-explicit implementation behind
+ * `geo.personalSpaces.publishEdit(...)`.
+ *
+ * @example
+ * ```ts
+ * import * as Ops from '@geoprotocol/geo-sdk/ops';
+ *
+ * const { ops } = Ops.entities.create({ name: 'Geo entity' });
+ * const tx = await geo.personalSpaces.publishEdit({
+ *   name: 'Create Geo entity',
+ *   spaceId,
+ *   author: spaceId,
+ *   ops,
+ * });
+ *
+ * await walletClient.sendTransaction({
+ *   to: tx.to,
+ *   data: tx.calldata,
+ * });
+ * ```
+ *
+ * @param context Client context containing network, contract, API, and fetch configuration.
+ * @param params Edit publication params plus the target personal space ID.
+ * @returns Edit ID, CID, target registry address, and calldata.
+ * @throws When the configured network is missing required contracts or edit publishing fails.
+ */
+export declare function publishEdit(context: GeoClientContext, params: PublishPersonalSpaceEditParams): Promise<{
+    editId: Id;
+    cid: `ipfs://${string}`;
+    to: `0x${string}`;
+    calldata: `0x${string}`;
+}>;
+//# sourceMappingURL=personal-spaces.d.ts.map

package/dist/src/client/personal-spaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"personal-spaces.d.ts","sourceRoot":"","sources":["../../../src/client/personal-spaces.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,KAAK,OAAO,EAA0C,KAAK,GAAG,EAAQ,MAAM,MAAM,CAAC;AAQ5F,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAGzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,MAAM,MAAM,yBAAyB,GAAG;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,EAAE,EAAE,KAAK,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,KAAK,MAAM,EAAE,CAAC;IACxB,aAAa,EAAE,EAAE,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,EAAE,EAAE,CAAC;CACX,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,OAAO,EAAE,EAAE,GAAG,MAAM,CAAC;IACrB,OAAO,EAAE,EAAE,GAAG,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,EAAE,GAAG,MAAM,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,GAAG,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,8BAA8B,GAAG,iBAAiB,GAAG;IAC/D,OAAO,EAAE,EAAE,GAAG,MAAM,CAAC;CACtB,CAAC;AAaF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,MAAM,CACpB,OAAO,EAAE,gBAAgB,EACzB,EAAE,IAAI,EAAE,cAAc,EAAE,EAAE,yBAAyB,GAClD,yBAAyB,CA4B3B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,QAAQ,CACtB,OAAO,EAAE,gBAAgB,EACzB,EAAE,OAAO,EAAE,OAAO,EAAE,aAAuB,EAAE,EAAE,2BAA2B;;;EAqB3E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,gBAAgB,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,CAe/G;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,8BAA8B;;;;;GAGlG"}

package/dist/src/client/personal-spaces.js

@@ -0,0 +1,198 @@
+import { createPublicClient, encodeFunctionData, http } from 'viem';
+import { EMPTY_SPACE_ID } from '../../contracts.js';
+import { SpaceRegistryAbi } from '../abis/index.js';
+import * as Account from '../core/account.js';
+import { PERSON_TYPE, SPACE_TYPE, TYPES_PROPERTY } from '../core/ids/system.js';
+import { getCreatePersonalSpaceCalldata } from '../encodings/get-create-personal-space-calldata.js';
+import { createEntity } from '../graph/create-entity.js';
+import { createRelation } from '../graph/create-relation.js';
+import * as IdUtils from '../id-utils.js';
+import { assertValid } from '../id-utils.js';
+import { requireGeoContract } from '../networks.js';
+import { EMPTY_SIGNATURE, TOPIC_DECLARED } from '../personal-space/constants.js';
+function idToBytes16(id, sourceHint) {
+    const normalized = id.startsWith('0x') ? id.slice(2) : id.replaceAll('-', '');
+    assertValid(normalized, sourceHint);
+    return `0x${normalized.toLowerCase()}`;
+}
+function bytes16ToBytes32LeftAligned(bytes16Hex) {
+    return `0x${bytes16Hex.slice(2)}${'0'.repeat(32)}`;
+}
+/**
+ * Builds the personal-space creation transaction and initial space content ops.
+ *
+ * The returned calldata registers the caller's address as a personal space.
+ * The returned ops create the space entity, the account entity, and the
+ * personal-space type relations that should be published after the space ID is
+ * available onchain.
+ *
+ * @example
+ * ```ts
+ * const tx = geo.personalSpaces.create({
+ *   name: 'Alice',
+ *   accountAddress: account.address,
+ * });
+ *
+ * await walletClient.sendTransaction({
+ *   to: tx.to,
+ *   data: tx.calldata,
+ * });
+ *
+ * // Once the transaction is mined and the space ID is known:
+ * await geo.personalSpaces.publishEdit({
+ *   name: 'Create personal space profile',
+ *   spaceId,
+ *   author: spaceId,
+ *   ops: tx.ops,
+ * });
+ * ```
+ *
+ * @param context Client context containing the target network configuration.
+ * @param params Space display name and account address to describe in initial ops.
+ * @returns Target registry address, calldata, generated entity IDs, and initial content ops.
+ * @throws When the configured network is missing `SPACE_REGISTRY_ADDRESS`.
+ */
+export function create(context, { name, accountAddress }) {
+    const spaceEntityId = IdUtils.generate();
+    const ops = [];
+    const { accountId, ops: accountOps } = Account.make(accountAddress);
+    ops.push(...accountOps);
+    const { ops: createSpaceEntityOps } = createEntity({
+        id: spaceEntityId,
+        name,
+        types: [SPACE_TYPE],
+    });
+    ops.push(...createSpaceEntityOps);
+    const { ops: personRelationOps } = createRelation({
+        fromEntity: spaceEntityId,
+        type: TYPES_PROPERTY,
+        toEntity: PERSON_TYPE,
+    });
+    ops.push(...personRelationOps);
+    return {
+        to: requireGeoContract(context.network, 'SPACE_REGISTRY_ADDRESS'),
+        calldata: getCreatePersonalSpaceCalldata(),
+        spaceEntityId,
+        accountId,
+        ops,
+    };
+}
+/**
+ * Builds calldata for setting a personal space topic.
+ *
+ * Call this right after creating the personal space and publishing its initial
+ * profile ops. For personal spaces, `authorSpaceId` defaults to `spaceId`.
+ *
+ * @example
+ * ```ts
+ * const topicTx = geo.personalSpaces.setTopic({
+ *   spaceId,
+ *   topicId: createSpace.spaceEntityId,
+ * });
+ *
+ * await walletClient.sendTransaction({
+ *   to: topicTx.to,
+ *   data: topicTx.calldata,
+ * });
+ * ```
+ *
+ * @param context Client context containing the target network configuration.
+ * @param params Space ID, topic entity ID, and optional author space ID.
+ * @returns Target registry address and calldata.
+ * @throws When an ID is invalid or the configured network is missing `SPACE_REGISTRY_ADDRESS`.
+ */
+export function setTopic(context, { spaceId, topicId, authorSpaceId = spaceId }) {
+    const authorSpaceIdBytes = idToBytes16(authorSpaceId, '`authorSpaceId` in `setTopic`');
+    const spaceIdBytes = idToBytes16(spaceId, '`spaceId` in `setTopic`');
+    const topicIdBytes = idToBytes16(topicId, '`topicId` in `setTopic`');
+    return {
+        to: requireGeoContract(context.network, 'SPACE_REGISTRY_ADDRESS'),
+        calldata: encodeFunctionData({
+            abi: SpaceRegistryAbi,
+            functionName: 'enter',
+            args: [
+                authorSpaceIdBytes,
+                spaceIdBytes,
+                TOPIC_DECLARED,
+                bytes16ToBytes32LeftAligned(topicIdBytes),
+                '0x',
+                EMPTY_SIGNATURE,
+            ],
+        }),
+    };
+}
+/**
+ * Checks whether an address already has a personal space on the configured network.
+ *
+ * The helper reads `addressToSpaceId(address)` from the configured
+ * `SPACE_REGISTRY_ADDRESS`. Pass `rpcUrl` to override the network's configured
+ * RPC URL for this lookup.
+ *
+ * @example
+ * ```ts
+ * const hasExistingSpace = await geo.personalSpaces.hasSpace({
+ *   address: account.address,
+ * });
+ *
+ * if (!hasExistingSpace) {
+ *   const tx = geo.personalSpaces.create({
+ *     name: 'Alice',
+ *     accountAddress: account.address,
+ *   });
+ *   await walletClient.sendTransaction({ to: tx.to, data: tx.calldata });
+ * }
+ * ```
+ *
+ * @param context Client context containing network and contract configuration.
+ * @param params Wallet or smart-account address plus optional RPC URL override.
+ * @returns `true` when the registry maps the address to a non-empty space ID.
+ * @throws When the configured network is missing `SPACE_REGISTRY_ADDRESS` or no RPC URL is available.
+ */
+export async function hasSpace(context, { address, rpcUrl }) {
+    const resolvedRpcUrl = rpcUrl ?? context.network.chain?.rpcUrl;
+    if (!resolvedRpcUrl) {
+        throw new Error(`Geo network "${context.network.name}" is missing an RPC URL`);
+    }
+    const publicClient = createPublicClient({ transport: http(resolvedRpcUrl) });
+    const spaceIdHex = (await publicClient.readContract({
+        address: requireGeoContract(context.network, 'SPACE_REGISTRY_ADDRESS'),
+        abi: SpaceRegistryAbi,
+        functionName: 'addressToSpaceId',
+        args: [address],
+    }));
+    return spaceIdHex.toLowerCase() !== EMPTY_SPACE_ID.toLowerCase();
+}
+/**
+ * Publishes an edit and returns calldata for submitting it to a personal space.
+ *
+ * This is the context-explicit implementation behind
+ * `geo.personalSpaces.publishEdit(...)`.
+ *
+ * @example
+ * ```ts
+ * import * as Ops from '@geoprotocol/geo-sdk/ops';
+ *
+ * const { ops } = Ops.entities.create({ name: 'Geo entity' });
+ * const tx = await geo.personalSpaces.publishEdit({
+ *   name: 'Create Geo entity',
+ *   spaceId,
+ *   author: spaceId,
+ *   ops,
+ * });
+ *
+ * await walletClient.sendTransaction({
+ *   to: tx.to,
+ *   data: tx.calldata,
+ * });
+ * ```
+ *
+ * @param context Client context containing network, contract, API, and fetch configuration.
+ * @param params Edit publication params plus the target personal space ID.
+ * @returns Edit ID, CID, target registry address, and calldata.
+ * @throws When the configured network is missing required contracts or edit publishing fails.
+ */
+export async function publishEdit(context, params) {
+    const { publishToSpace } = await import('./edits.js');
+    return publishToSpace(context, params);
+}
+//# sourceMappingURL=personal-spaces.js.map

package/dist/src/client/personal-spaces.js.map

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