feat: Pub/sub

DEVELOPER_GUIDE.md

@@ -17,7 +17,6 @@ graph TD
   subgraph Tier0 ["Tier 0 (Publish First)"]
     google_cloud["google_cloud"]
     google_cloud_protobuf["protobuf"]
-    google_cloud_pubsub["pubsub"]
   end
 
   subgraph Tier1 ["Tier 1"]
@@ -33,6 +32,7 @@ graph TD
     google_cloud_language_v2["language_v2"]
     google_cloud_location["location"]
     google_cloud_longrunning["longrunning"]
+    google_cloud_pubsub["pubsub"]
     google_cloud_storage["storage"]
   end
 
@@ -93,6 +93,9 @@ graph TD
   google_cloud_logging_v2 --> google_cloud_rpc
   google_cloud_longrunning --> google_cloud_protobuf
   google_cloud_longrunning --> google_cloud_rpc
+  google_cloud_pubsub --> google_cloud
+  google_cloud_pubsub --> google_cloud_protobuf
+  google_cloud_pubsub --> google_cloud_rpc
   google_cloud_rpc --> google_cloud_protobuf
   google_cloud_secretmanager_v1 --> google_cloud_iam_v1
   google_cloud_secretmanager_v1 --> google_cloud_location

pkgs/google_cloud_pubsub/README.md

@@ -17,9 +17,59 @@ A Dart client for Google Cloud Pub/Sub.
 > feedback, suggestions, and comments, please file an issue in the
 > [bug tracker](https://github.com/googleapis/google-cloud-dart/issues).
 
-## Usage
+## Using Google Cloud PubSub
 
-This package contains generated gRPC client code for Google Cloud Pub/Sub.
+All access to Google Cloud Pub/Sub is made through the `PubSub` class.
 
-For details on how to use the generated gRPC client, please refer to the gRPC and Protobuf documentation.
+```dart
+import 'dart:convert';
+import 'package:google_cloud_pubsub/google_cloud_pubsub.dart';
 
+void main() async {
+  // Note: You must provide an `authenticator` for authentication in production.
+  final pubSub = PubSub(
+    projectId: 'your-project-id',
+    authenticator: await applicationDefaultCredentialsAuthenticator(
+      ['https://www.googleapis.com/auth/pubsub'],
+    ),
+  );
+
+  // Create a topic.
+  final topic = await pubSub.topic('put-your-topic-name-here').create();
+
+  // Create a subscription to that topic.
+  final subscription = await pubSub
+      .subscription('put-your-subscription-name-here')
+      .create(topic: topic.name);
+
+  // Publish a message.
+  await topic.publish(utf8.encode('message 1'));
+
+  // Pull messages from the subscription.
+  final messages = await subscription.pull(maxMessages: 1);
+
+  for (final receivedMessage in messages) {
+    print('Received message: ${utf8.decode(receivedMessage.data)}');
+
+    // Acknowledge the message.
+    await subscription.acknowledge([receivedMessage.ackId]);
+  }
+
+  print(
+    'Your topic is available at:\n'
+    'https://pubsub.googleapis.com/v1/${topic.name}',
+  );
+
+  // Clean up.
+  await subscription.delete();
+  await topic.delete();
+
+  pubSub.close();
+}
+```
+
+> [!NOTE]
+> You must [set up authentication][] before using this package outside of 
+> Google Cloud.
+
+[set up authentication]: https://docs.cloud.google.com/pubsub/docs/reference/libraries#authentication

pkgs/google_cloud_pubsub/example/example.dart

@@ -0,0 +1,40 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import 'dart:async';
+
+import 'package:google_cloud_pubsub/google_cloud_pubsub.dart';
+
+/// An example demonstrating how to initialize and use the [PubSub] client
+/// with Google Application Default Credentials (ADC) authentication.
+Future<void> main() async {
+  // Asynchronously construct the ADC authenticator with the required Pub/Sub scope.
+  final authenticator = await applicationDefaultCredentialsAuthenticator([
+    'https://www.googleapis.com/auth/pubsub',
+  ]);
+
+  // Pass the authenticator to the PubSub client constructor.
+  final pubsub = PubSub(
+    projectId: 'my-project-id',
+    authenticator: authenticator,
+  );
+
+  try {
+    // The client will use the authenticator to make authenticated requests.
+    final topic = pubsub.topic('my-topic');
+    print('Successfully initialized client for topic: ${topic.id}');
+  } finally {
+    await pubsub.close();
+  }
+}

pkgs/google_cloud_pubsub/lib/google_cloud_pubsub.dart

@@ -12,7 +12,15 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-export 'src/generated/google/pubsub/v1/pubsub.pb.dart';
-export 'src/generated/google/pubsub/v1/pubsub.pbgrpc.dart';
-export 'src/generated/google/pubsub/v1/schema.pb.dart';
-export 'src/generated/google/pubsub/v1/schema.pbgrpc.dart';
+export 'package:grpc/grpc.dart'
+    show
+        BaseAuthenticator,
+        ComputeEngineAuthenticator,
+        ServiceAccountAuthenticator,
+        applicationDefaultCredentialsAuthenticator;
+
+export 'src/client.dart' show PubSub;
+export 'src/exceptions.dart';
+export 'src/message.dart' show Message, ReceivedMessage;
+export 'src/subscription.dart' show Subscription;
+export 'src/topic.dart' show Topic;