PIKD SDK API for Dart

Typed Dart client for the PIKD /sdk/v1 API. It provides authentication, collectibles, challenges, profiles, collections, leaderboards, feeds, and AR session telemetry for applications that compose individual PIKD capabilities.

Release candidate: pikd_flutter_api version 0.8.0-beta.5.

Requirements

  • Dart 3.3 or later
  • A PIKD SDK key issued for your tenant
  • A separate written SDK agreement with ELEOS WORLD LTD

Installation

After the package is published, add it from pub.dev:

dependencies:
  pikd_flutter_api: ^0.8.0-beta.5

Then resolve dependencies:

dart pub get

Configure the client

Do not hard-code production SDK keys in source control. Inject them through your environment or deployment system and add the key to an ApiClient:

import 'package:pikd_flutter_api/api.dart';

final client = ApiClient(basePath: 'https://api.pikd.app/sdk/v1')
  ..addDefaultHeader('x-pikd-sdk-key', sdkKey);

final collectiblesApi = CollectiblesApi(client);

Tier 1 and higher integrations should also pass the opaque PIKD user reference required by the selected endpoint. Do not send personally identifiable user data as the user reference.

Find nearby collectibles

final collectibles = await collectiblesApi.getNearbyCollectibles(
      latitude,
      longitude,
      radiusM: 250,
      xPikdUser: pikdUserReference,
    ) ??
    const <Collectible>[];

for (final collectible in collectibles) {
  print('${collectible.id}: ${collectible.title}');
}

Collect an item

Anonymous Tier-0 integrations can omit userRefBody:

final result = await collectiblesApi.collectCollectible(collectibleId);
print(result?.status);

Identified integrations pass their opaque host reference:

final result = await collectiblesApi.collectCollectible(
  collectibleId,
  userRefBody: UserRefBody(userRef: hostUserReference),
);

API failures throw ApiException. Handle them at the boundary where your app maps network errors to user-visible states.

Authentication

The package supports the authentication schemes generated from the PIKD OpenAPI contract. Most SDK endpoints use the tenant key in the x-pikd-sdk-key header. Tier 1 integrations can exchange a signed host assertion through AuthApi for an opaque PIKD user identifier.

Available APIs

  • AuthApi
  • ChallengesApi
  • CollectiblesApi
  • FeedApi
  • LeaderboardApi
  • ProfileApi
  • TelemetryApi

Generated endpoint and model references are included under doc/. A runnable nearby-collectibles example is available in example/pikd_flutter_api_example.dart.

Regeneration

The client implementation is generated from the versioned PIKD OpenAPI contract. Public metadata, this README, the changelog, the license, and examples are intentionally protected by .openapi-generator-ignore and must be reviewed separately from generated source changes.

License

This package is proprietary software. Use requires a written SDK agreement with ELEOS WORLD LTD. See LICENSE and the PIKD SDK license page.

Libraries

api